@3fn/core 13.0.0 → 14.0.0

package/dist/mcp/application-mcp.js

@@ -19238,6 +19238,30 @@ var ComponentMCPServer = class {
     this.stalenessGate.markIndexed();
     await this.server.connect(transport);
     console.error(`[${SERVER_NAME}] Server running on stdio`);
+    this.setupShutdownHandlers();
+  }
+  /**
+   * Self-exit on stdin EOF and fatal signals. A stdio MCP server whose parent client
+   * died (or gracefully closed the pipe) has no one to serve, but the file watcher
+   * keeps the event loop alive forever — found live at Spec 122 U3 (~230 orphaned
+   * servers accumulated across harness runs). Exiting on EOF also makes graceful
+   * client closes immediate: the MCP SDK's StdioClientTransport.close() ends stdin
+   * and waits up to 2s for exactly this exit before escalating to SIGTERM.
+   */
+  setupShutdownHandlers() {
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      console.error(`[${SERVER_NAME}] Shutting down...`);
+      this.fileWatcher.stop();
+      await this.server.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    process.stdin.on("end", shutdown);
+    process.stdin.on("close", shutdown);
   }
   registerHandlers() {
     this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));

package/dist/mcp/docs-mcp.js

@@ -14341,6 +14341,7 @@ function resolveSection(content, filePath, opts) {
 }
 
 // mcp-server/src/indexer/cross-ref-parser.ts
+var BARE_ID_GRAMMAR = /^[a-z0-9][a-z0-9-]*$/;
 function extractCrossReferences(content, _filePath) {
   const lines = content.split("\n");
   const references = [];
@@ -14363,6 +14364,14 @@ function extractCrossReferences(content, _filePath) {
           section: currentSection,
           lineNumber: i + 1
         });
+      } else if (BARE_ID_GRAMMAR.test(target) && !/[/.:#]/.test(target)) {
+        references.push({
+          target,
+          context,
+          section: currentSection,
+          lineNumber: i + 1,
+          kind: "id-candidate"
+        });
       }
     }
   }
@@ -14380,7 +14389,7 @@ function estimateTokenCount(content) {
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 function determineIndexHealth(options) {
-  const { indexedDocuments, directoryPath, lastIndexTime } = options;
+  const { indexedDocuments, directoryPath, lastIndexTime, crossRefTotals } = options;
   const errors = [];
   const warnings = [];
   const expectedDocs = getExpectedDocuments(directoryPath);
@@ -14400,7 +14409,15 @@ function determineIndexHealth(options) {
   if (malformedDocs.length > 0) {
     warnings.push(`Malformed metadata: ${malformedDocs.join(", ")}`);
   }
+  if (crossRefTotals && crossRefTotals.droppedBareIdCount > 0) {
+    warnings.push(
+      `${crossRefTotals.droppedBareIdCount} unresolved bare-id link targets \u2014 run scan-cross-references.sh for the list`
+    );
+  }
   const metrics = calculateIndexMetrics(indexedDocuments);
+  if (crossRefTotals) {
+    metrics.totalCrossReferences = crossRefTotals.validatedCount;
+  }
   let status;
   if (errors.length > 0) {
     status = "failed";
@@ -14664,6 +14681,25 @@ var DocumentIndexer = class {
     this.idIndex = /* @__PURE__ */ new Map();
     // id → indexedKey
     this.legacyPathIndex = /* @__PURE__ */ new Map();
+    // normalizedLegacyPath → indexedKey
+    /**
+     * Validated cross-references per indexed key (Spec 119-B OB-1, Decision 1:
+     * extract-then-validate at INDEX time, one validation point). indexFile
+     * stores the raw parser output (bare-id candidates still tagged); the
+     * post-index validation pass (or reindexFile's inline pass) replaces it with
+     * the validated, TAG-STRIPPED set — the candidate tag never escapes the
+     * indexer. All read surfaces (list_cross_references, getDocumentSummary,
+     * index-health metrics) consume THIS map, never re-extract, so the
+     * crossReferences count is a stable index property.
+     */
+    this.crossRefsByKey = /* @__PURE__ */ new Map();
+    /**
+     * Bare-id candidates dropped by validation (target not in idIndex) — the
+     * typo-suspicious class. Surfaced on two channels (design Component 6):
+     * scan-cross-references.sh lists individually; index-health emits ONE
+     * aggregate warning when count > 0.
+     */
+    this.droppedIdCandidates = [];
     this.logsDirectory = logsDirectory;
   }
   /**
@@ -14682,11 +14718,14 @@ var DocumentIndexer = class {
     this.documentContent.clear();
     this.idIndex.clear();
     this.legacyPathIndex.clear();
+    this.crossRefsByKey.clear();
+    this.droppedIdCandidates = [];
     const files = this.scanDirectory(directoryPath);
     for (const filePath of files) {
       await this.indexFile(filePath);
     }
     this.seedLegacyPaths();
+    this.validateAllCrossReferences();
     this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
     this.logIndexStateChange("indexing_completed", {
       directoryPath,
@@ -14704,10 +14743,13 @@ var DocumentIndexer = class {
       this.pruneAddressingEntriesForKey(filePath);
       this.documentMap.delete(filePath);
       this.documentContent.delete(filePath);
+      this.crossRefsByKey.delete(filePath);
+      this.droppedIdCandidates = this.droppedIdCandidates.filter((d) => d.sourceKey !== filePath);
       this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
       return;
     }
     await this.indexFile(filePath);
+    this.validateCrossReferencesForKey(filePath);
     this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
   }
   /**
@@ -14745,10 +14787,11 @@ var DocumentIndexer = class {
    * @param filePath - Path to document
    */
   getDocumentSummary(filePath) {
-    const content = this.getDocumentContent(filePath);
+    const { indexedKey } = this.resolveRef(filePath);
+    const content = this.documentContent.get(indexedKey);
     const metadata = extractMetadata(content);
     const outline = extractHeadingStructure(content);
-    const crossReferences = extractCrossReferences(content, filePath);
+    const crossReferences = this.crossRefsByKey.get(indexedKey) ?? [];
     const crossReferenceInfo = crossReferences.map((ref) => ({
       target: ref.target,
       context: ref.context,
@@ -14858,12 +14901,65 @@ ${candidateLines}`
   /**
    * List cross-references in a document
    * Returns links without following them
-   * 
-   * @param filePath - Path to document
+   *
+   * Spec 119-B OB-1: the incoming ref routes through the SAME resolver chain
+   * as every other document-addressed tool (id → indexed key → legacy path,
+   * D5), and the result is the VALIDATED index-time set — `.md` path refs
+   * unchanged, bare-id refs enumerated with target = the doc id; dropped
+   * candidates never appear. Public shape unchanged (no kind tag).
+   *
+   * @param filePath - Document ref: id, indexed relative path, or legacy path
    */
   listCrossReferences(filePath) {
-    const content = this.getDocumentContent(filePath);
-    return extractCrossReferences(content, filePath);
+    const { indexedKey } = this.resolveRef(filePath);
+    return this.crossRefsByKey.get(indexedKey) ?? [];
+  }
+  /**
+   * Bare-id candidates dropped by validation (Spec 119-B OB-1) — the
+   * typo-suspicious class surfaced via index-health's aggregate warning and
+   * scan-cross-references.sh's individual listing.
+   */
+  getDroppedIdCandidates() {
+    return this.droppedIdCandidates;
+  }
+  /**
+   * Validate ALL stored cross-reference sets against the completed idIndex
+   * (the post-index hook — Spec 119-B OB-1, Decision 1's single validation
+   * point). Resets the dropped-candidate record.
+   */
+  validateAllCrossReferences() {
+    this.droppedIdCandidates = [];
+    for (const key of this.crossRefsByKey.keys()) {
+      this.validateCrossReferencesForKey(key);
+    }
+  }
+  /**
+   * Validate one document's stored cross-references against the CURRENT
+   * idIndex. `.md` path refs pass through untouched; bare-id candidates are
+   * kept iff their target is a known doc id (tag stripped — it never escapes
+   * the indexer) and dropped-with-record otherwise.
+   */
+  validateCrossReferencesForKey(key) {
+    const raw = this.crossRefsByKey.get(key);
+    if (!raw) return;
+    this.droppedIdCandidates = this.droppedIdCandidates.filter((d) => d.sourceKey !== key);
+    const validated = [];
+    for (const ref of raw) {
+      if (ref.kind !== "id-candidate") {
+        validated.push(ref);
+      } else if (this.idIndex.has(ref.target)) {
+        const { kind: _kind, ...publicRef } = ref;
+        validated.push(publicRef);
+      } else {
+        this.droppedIdCandidates.push({
+          sourceKey: key,
+          target: ref.target,
+          section: ref.section,
+          lineNumber: ref.lineNumber
+        });
+      }
+    }
+    this.crossRefsByKey.set(key, validated);
   }
   /**
    * Validate metadata for a document
@@ -14957,6 +15053,7 @@ ${candidateLines}`
       viability: frontmatter.viability
     };
     this.documentMap.set(filePath, documentMetadata);
+    this.crossRefsByKey.set(filePath, extractCrossReferences(content, filePath));
     for (const [existingId, existingKey] of this.idIndex) {
       if (existingKey === filePath && existingId !== id) this.idIndex.delete(existingId);
     }
@@ -15119,10 +15216,16 @@ ${candidateLines}`
       this.logIndexStateChange("validation_completed", { status: health2.status, errors: health2.errors });
       return health2;
     }
+    let validatedCount = 0;
+    for (const refs of this.crossRefsByKey.values()) validatedCount += refs.length;
     const health = determineIndexHealth({
       indexedDocuments: this.documentContent,
       directoryPath: this.directoryPath,
-      lastIndexTime: this.lastIndexTime
+      lastIndexTime: this.lastIndexTime,
+      crossRefTotals: {
+        validatedCount,
+        droppedBareIdCount: this.droppedIdCandidates.length
+      }
     });
     this.logIndexStateChange("validation_completed", {
       status: health.status,
@@ -16421,13 +16524,13 @@ function formatMcpResponse4(result) {
 // mcp-server/src/tools/list-cross-references.ts
 var listCrossReferencesTool = {
   name: "list_cross_references",
-  description: "List cross-references in a document. Returns all referenced documents with context, source section, and line number.",
+  description: "List cross-references in a document. Returns all referenced documents with context, source section, and line number. Enumerates both `.md`-path links (target = the linked path, verbatim) and bare-id links validated against the doc-id index (target = the doc id); unresolvable bare-id targets are excluded (surfaced via index-health). Addressing contract (D5): the `path` parameter resolves through the same strategy chain as the other document tools \u2014 doc id, then indexed relative path, then legacy `.kiro/steering/\u2026` path.",
   inputSchema: {
     type: "object",
     properties: {
       path: {
         type: "string",
-        description: 'Document path (e.g., ".kiro/steering/Component Development Guide.md")'
+        description: 'Document ref: doc id (e.g., "token-governance"), indexed relative path, or legacy `.kiro/steering/\u2026` path \u2014 same resolver chain as get_document_summary'
       }
     },
     required: ["path"]
@@ -16851,7 +16954,15 @@ var MCPDocumentationServer = class {
     this.isRunning = false;
   }
   /**
-   * Set up graceful shutdown handlers
+   * Set up graceful shutdown handlers.
+   *
+   * stdin EOF ('end'/'close') is a first-class shutdown trigger: a stdio MCP server
+   * whose parent client died (or gracefully closed the pipe) has no one to serve, but
+   * the file watcher keeps the event loop alive forever — found live at Spec 122 U3
+   * (~230 orphaned servers accumulated across harness runs, wedging later boots).
+   * Self-exiting on EOF also makes graceful client closes immediate: the MCP SDK's
+   * StdioClientTransport.close() ends stdin and waits up to 2s for exactly this exit
+   * before escalating to SIGTERM.
    */
   setupShutdownHandlers() {
     const shutdown = async () => {
@@ -16860,6 +16971,8 @@ var MCPDocumentationServer = class {
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
+    process.stdin.on("end", shutdown);
+    process.stdin.on("close", shutdown);
   }
 };
 async function main() {
@@ -16882,10 +16995,12 @@ async function main() {
   const server = new MCPDocumentationServer(steeringDir);
   await server.start();
 }
-main().catch((error2) => {
-  console.error("[MCP Server] Fatal error:", error2);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((error2) => {
+    console.error("[MCP Server] Fatal error:", error2);
+    process.exit(1);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MCPDocumentationServer,

package/dist/mcp/product-mcp.js

@@ -24567,6 +24567,31 @@ var ProductMCPServer = class {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
     console.error(`[${SERVER_NAME4}] Server running on stdio`);
+    this.setupShutdownHandlers();
+  }
+  /**
+   * Self-exit on stdin EOF and fatal signals. A stdio MCP server whose parent client
+   * died (or gracefully closed the pipe) has no one to serve, but the file watcher
+   * keeps the event loop alive forever — found live at Spec 122 U3 (~230 orphaned
+   * servers accumulated across harness runs, this server the most-leaked of the
+   * three). Exiting on EOF also makes graceful client closes immediate: the MCP
+   * SDK's StdioClientTransport.close() ends stdin and waits up to 2s for exactly
+   * this exit before escalating to SIGTERM.
+   */
+  setupShutdownHandlers() {
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      console.error(`[${SERVER_NAME4}] Shutting down...`);
+      this.fileWatcher?.close();
+      await this.server.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    process.stdin.on("end", shutdown);
+    process.stdin.on("close", shutdown);
   }
   startFileWatcher() {
     if (!fs7.existsSync(this.productDir)) return;

package/dist/tokens/OpacityTokens.js

@@ -108,7 +108,7 @@ exports.opacityTokens = {
         category: PrimitiveToken_1.TokenCategory.OPACITY,
         baseValue: exports.OPACITY_BASE_VALUE * 6,
         familyBaseValue: exports.OPACITY_BASE_VALUE,
-        description: 'Disabled state - faded, very strong overlay',
+        description: 'Very strong transparency - background scrims and modal overlays (referenced by opacity.heavy)',
         mathematicalRelationship: 'base × 6 = 0.08 × 6 = 0.48',
         baselineGridAlignment: false,
         isStrategicFlexibility: false,

package/dist/tokens/semantic/BlendTokens.d.ts

@@ -16,7 +16,7 @@
  * - blendHoverLighter: Hover feedback on dark backgrounds (8% lighter)
  * - blendPressedDarker: Pressed state feedback with darkening (12% darker)
  * - blendFocusSaturate: Focus state with increased saturation (8% more saturated)
- * - blendDisabledDesaturate: Disabled state with decreased saturation (12% less saturated)
+ * - blendDisabledDesaturate: DEPRECATED 2026-07-15 — DesignerPunk has no disabled states
  * - blendContainerHoverDarker: Subtle container hover feedback (4% darker)
  * - color.icon.opticalBalance: Icon optical weight compensation (8% lighter)
  *
@@ -42,6 +42,12 @@ export interface SemanticBlendToken {
     context: string;
     /** Detailed description of semantic meaning and appropriate usage */
     description: string;
+    /** Token is deprecated — do not use in new work; flows to DTCG $extensions.designerpunk.deprecated */
+    deprecated?: boolean;
+    /** ISO date the deprecation took effect */
+    deprecatedSince?: string;
+    /** Why the token was deprecated and what to do instead */
+    deprecatedReason?: string;
 }
 /**
  * Semantic blend tokens for common interaction states
@@ -87,8 +93,9 @@ export declare function validateBlendTokenCount(): boolean;
  *    → Creates vibrant, attention-drawing appearance for focused elements
  *
  * 5. Disabled states?
- *    → Use blend.disabledDesaturate (12% less saturated)
- *    → Creates muted appearance indicating non-interactive state
+ *    → DO NOT style disabled states. DesignerPunk does not support disabled states —
+ *      if an action is unavailable, do not render the component (adjudicated 2026-07-15).
+ *    → blend.disabledDesaturate is DEPRECATED and scheduled for removal at the next major.
  *
  * 6. Large container/surface hover?
  *    → Use blend.containerHoverDarker (4% darker)

package/dist/tokens/semantic/BlendTokens.js

@@ -17,7 +17,7 @@
  * - blendHoverLighter: Hover feedback on dark backgrounds (8% lighter)
  * - blendPressedDarker: Pressed state feedback with darkening (12% darker)
  * - blendFocusSaturate: Focus state with increased saturation (8% more saturated)
- * - blendDisabledDesaturate: Disabled state with decreased saturation (12% less saturated)
+ * - blendDisabledDesaturate: DEPRECATED 2026-07-15 — DesignerPunk has no disabled states
  * - blendContainerHoverDarker: Subtle container hover feedback (4% darker)
  * - color.icon.opticalBalance: Icon optical weight compensation (8% lighter)
  *
@@ -84,6 +84,14 @@ exports.blendTokens = {
         context: 'Focus state feedback - more vibrant, attention-drawing color',
         description: 'Blend for focus states with saturation increase (8% more saturated) - creates energized, attention-drawing appearance for focused interactive elements'
     },
+    /**
+     * @deprecated 2026-07-15 — DesignerPunk does not support disabled states
+     * (Button-CTA disabled-state adjudication, ruled REMOVE; the no-disabled-states
+     * philosophy holds corpus-wide). If an action is unavailable, do not render the
+     * component. Retained for backward compatibility; scheduled for removal in the
+     * next major version of @3fn/core. For non-disabled desaturation needs, use the
+     * generic desaturate utilities with primitive blend tokens.
+     */
     'blend.disabledDesaturate': {
         name: 'blend.disabledDesaturate',
         primitiveReferences: {
@@ -91,8 +99,11 @@ exports.blendTokens = {
         },
         direction: BlendTokens_1.BlendDirection.DESATURATE,
         category: 'interaction',
-        context: 'Disabled state appearance - muted, inactive color',
-        description: 'Blend for disabled states with desaturation (12% less saturated) - creates muted, inactive appearance indicating non-interactive state'
+        context: 'DEPRECATED - disabled states are not supported in DesignerPunk',
+        description: 'DEPRECATED (2026-07-15): DesignerPunk does not support disabled states — if an action is unavailable, do not render the component. Formerly: blend for disabled states with desaturation (12% less saturated). Scheduled for removal in the next major version.',
+        deprecated: true,
+        deprecatedSince: '2026-07-15',
+        deprecatedReason: 'No-disabled-states philosophy holds corpus-wide (Button-CTA adjudication, 2026-07-15). Unavailable actions should not be rendered; state_loading covers in-flight async actions.'
     },
     'blend.containerHoverDarker': {
         name: 'blend.containerHoverDarker',
@@ -166,8 +177,9 @@ function validateBlendTokenCount() {
  *    → Creates vibrant, attention-drawing appearance for focused elements
  *
  * 5. Disabled states?
- *    → Use blend.disabledDesaturate (12% less saturated)
- *    → Creates muted appearance indicating non-interactive state
+ *    → DO NOT style disabled states. DesignerPunk does not support disabled states —
+ *      if an action is unavailable, do not render the component (adjudicated 2026-07-15).
+ *    → blend.disabledDesaturate is DEPRECATED and scheduled for removal at the next major.
  *
  * 6. Large container/surface hover?
  *    → Use blend.containerHoverDarker (4% darker)

package/dist/tokens/semantic/OpacityTokens.d.ts

@@ -6,10 +6,10 @@
  * the design system while maintaining semantic meaning.
  *
  * Opacity values:
- * - subtle: 0.9 (90%) - Minimal transparency for subtle effects
- * - medium: 0.7 (70%) - Moderate transparency for overlays
- * - heavy: 0.5 (50%) - Strong transparency for backgrounds
- * - ghost: 0.3 (30%) - Maximum transparency for ghost effects
+ * - subtle: opacity088 (88%) - Minimal transparency for subtle effects
+ * - medium: opacity072 (72%) - Moderate transparency for overlays
+ * - heavy: opacity048 (48%) - Strong transparency for backgrounds
+ * - ghost: opacity032 (32%) - Maximum transparency for ghost effects
  *
  * All opacity tokens reference primitive opacity values that can be applied
  * to any color or surface for consistent transparency effects.

package/dist/tokens/semantic/OpacityTokens.js

@@ -7,10 +7,10 @@
  * the design system while maintaining semantic meaning.
  *
  * Opacity values:
- * - subtle: 0.9 (90%) - Minimal transparency for subtle effects
- * - medium: 0.7 (70%) - Moderate transparency for overlays
- * - heavy: 0.5 (50%) - Strong transparency for backgrounds
- * - ghost: 0.3 (30%) - Maximum transparency for ghost effects
+ * - subtle: opacity088 (88%) - Minimal transparency for subtle effects
+ * - medium: opacity072 (72%) - Moderate transparency for overlays
+ * - heavy: opacity048 (48%) - Strong transparency for backgrounds
+ * - ghost: opacity032 (32%) - Maximum transparency for ghost effects
  *
  * All opacity tokens reference primitive opacity values that can be applied
  * to any color or surface for consistent transparency effects.

package/dist/types/ComponentTypes.d.ts

@@ -64,7 +64,7 @@
  * }
  * ```
  *
- * @see {@link https://github.com/3fn/DesignerPunkv2/blob/main/.kiro/specs/011-inset-token-renaming/design.md | Inset Token Renaming Design}
+ * @see {@link https://github.com/3fn/DesignerPunk/blob/main/.kiro/specs/011-inset-token-renaming/design.md | Inset Token Renaming Design}
  */
 export type InsetPadding = 'inset050' | 'inset100' | 'inset150' | 'inset200' | 'inset300' | 'inset400';
 //# sourceMappingURL=ComponentTypes.d.ts.map

package/dist/types/generated/TokenTypes.d.ts

@@ -6,7 +6,7 @@
  *
  * To regenerate: npm run generate:types
  *
- * Generated: 2026-07-05T14:35:59.520Z
+ * Generated: 2026-08-12T03:23:16.669Z
  */
 /**
  * Union type of all semantic color token names

package/dist/types/generated/TokenTypes.js

@@ -7,7 +7,7 @@
  *
  * To regenerate: npm run generate:types
  *
- * Generated: 2026-07-05T14:35:59.520Z
+ * Generated: 2026-08-12T03:23:16.669Z
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isColorTokenName = isColorTokenName;

package/dist/validators/StemmaTokenUsageValidator.js

@@ -208,9 +208,10 @@ exports.TOKEN_CATEGORIES = {
         'border.default', 'border.strong',
         'radius.100', 'radius.150', 'radius.200',
     ],
+    // blend.disabledDesaturate removed 2026-07-15: deprecated (no-disabled-states
+    // philosophy) — the validator must not suggest it for new component work
     blend: [
-        'blend.hoverDarker', 'blend.pressedDarker',
-        'blend.disabledDesaturate', 'blend.iconLighter',
+        'blend.hoverDarker', 'blend.pressedDarker', 'blend.iconLighter',
     ],
 };
 /**

package/dist/web/DesignTokens.web.css

@@ -1,6 +1,6 @@
 /**
  * DesignerPunk Design System - Web Tokens
- * Generated: 2026-07-05T13:53:05.410Z
+ * Generated: 2026-08-02T19:49:06.807Z
  * Version: 1.0.0
  * Platform: Web (CSS Custom Properties)
  *

package/governance/Component-Development-Guide.md

@@ -61,7 +61,7 @@ description: Guide for building components with appropriate token usage, True Na
 4. ✅ **Icon Integration Anti-Patterns** (what NOT to do)
 5. ✅ **Icon Integration Checklist** (verification steps)
 
-**WHEN implementing interaction states (hover, pressed, focus, disabled) THEN read:**
+**WHEN implementing interaction states (hover, pressed, focus) THEN read:**
 1. ✅ **Blend Utility Integration** (how to use blend utilities for state colors)
 2. ✅ **Semantic Blend Token Reference** (which token/function for each state)
 3. ✅ **Blend Utility Anti-Patterns** (what NOT to do - no opacity, no filters)
@@ -433,7 +433,8 @@ export interface ButtonCTAProps {
   variant?: 'primary' | 'secondary' | 'danger';  // ✅ Use variant
   size?: 'small' | 'medium' | 'large';
   icon?: string;
-  disabled?: boolean;
+  // No `disabled` prop — DesignerPunk components do not support disabled
+  // states (see "No Disabled States" under Behavioral Contracts Workflow).
 }
 ```
 
@@ -494,14 +495,27 @@ Author `contracts.yaml` after `types.ts` and before platform implementation. Con
 ### Naming Convention
 
 All contract names follow `{category}_{concept}` in `snake_case`:
-- `interaction_focusable`, `state_disabled`, `accessibility_reduced_motion`
+- `interaction_focusable`, `state_error`, `accessibility_reduced_motion`
 - 10 categories: accessibility, animation, composition, content, interaction, layout, performance, state, validation, visual
 
+### No Disabled States
+
+**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 holds corpus-wide with zero exceptions. Every component's `contracts.yaml` MUST instead carry the standardized exclusion block:
+
+```yaml
+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
+```
+
+If an action is temporarily unavailable, use one of these alternatives instead: `state_loading` (in-flight async operation), validate-on-press/validate-on-blur (surface the error rather than disabling the trigger), or don't render the component (no valid path forward). See Component-Templates.md § "No Disabled States — Standardized Exclusion" for the full rationale and reference implementation.
+
 ### Concept Catalog Consultation
 
 Before naming a contract, query the Concept Catalog via MCP:
 ```
-get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Concept Catalog" })
+get_section({ path: "contract-system-reference", heading: "Concept Catalog" })
 ```
 - Use existing catalog concepts whenever possible
 - If a behavior needs a new concept, propose a catalog addition (ballot measure) before using it
@@ -517,7 +531,7 @@ get_section({ path: ".kiro/steering/Contract-System-Reference.md", heading: "Con
 
 For the full contract system (taxonomy, canonical format, classification rules, inheritance patterns):
 ```
-get_document_full({ path: ".kiro/steering/Contract-System-Reference.md" })
+get_document_full({ path: "contract-system-reference" })
 ```
 
 ---
@@ -1036,7 +1050,7 @@ theme.colorActionPrimary
 
 ### Overview
 
-Blend utilities enable components to create new opaque colors for interaction states (hover, pressed, focus, disabled) rather than using opacity-based workarounds. All components should use blend utilities for state color modifications.
+Blend utilities enable components to create new opaque colors for interaction states (hover, pressed, focus) rather than using opacity-based workarounds. All components should use blend utilities for state color modifications.
 
 ### Why Blend Utilities Over CSS Filters
 
@@ -1064,7 +1078,7 @@ Blend utilities enable components to create new opaque colors for interaction st
 
 - Importing `getBlendUtilities()` from the theme-aware blend utilities module
 - Initializing blend utilities in the constructor
-- Calculating state colors (hover, pressed, disabled, icon) in `connectedCallback()`
+- Calculating state colors (hover, pressed, icon) in `connectedCallback()`
 - Applying calculated colors via CSS custom properties
 - Retry pattern for handling CSS custom property timing
 
@@ -1076,7 +1090,6 @@ Blend utilities enable components to create new opaque colors for interaction st
 - Hover state colors (darken or lighten based on background)
 - Pressed state colors (stronger darkening than hover)
 - Focus state colors (increased saturation for emphasis)
-- Disabled state colors (desaturation for muted appearance)
 - Icon optical balance (lightening for visual weight compensation)
 
 ### Web Platform Usage
@@ -1096,7 +1109,6 @@ class MyComponent extends HTMLElement {
     // Calculate state colors
     this._hoverColor = blendUtils.hoverColor(primaryColor);      // 8% darker
     this._pressedColor = blendUtils.pressedColor(primaryColor);  // 12% darker
-    this._disabledColor = blendUtils.disabledColor(primaryColor); // 12% desaturated
     this._focusColor = blendUtils.focusColor(primaryColor);      // 8% more saturated
   }
 }
@@ -1145,7 +1157,6 @@ fun MyComponent(primaryColor: Color) {
 | Hover (dark bg) | `blend.hoverLighter` | `lighterBlend(color, 0.08)` | 8% lighter |
 | Pressed | `blend.pressedDarker` | `pressedColor()` | 12% darker |
 | Focus | `blend.focusSaturate` | `focusColor()` | 8% more saturated |
-| Disabled | `blend.disabledDesaturate` | `disabledColor()` | 12% desaturated |
 | Container hover | `blend.containerHoverDarker` | `darkerBlend(color, 0.04)` | 4% darker |
 | Icon optical | `color.icon.opticalBalance` | `iconColor()` | 8% lighter |
 
@@ -1464,7 +1475,7 @@ All component-scoped CSS custom properties MUST use the `--_[abbrev]-*` naming p
 | Button-CTA | `_cta` | `--_cta-hover-bg`, `--_cta-pressed-bg` |
 | Button-VerticalList-Item | `_vlbi` | `--_vlbi-background`, `--_vlbi-border-color` |
 | ButtonIcon | `_bi` | `--_bi-hover-bg`, `--_bi-icon-color` |
-| Input-Text-Base | `_itb` | `--_itb-focus-color`, `--_itb-disabled-color` |
+| Input-Text-Base | `_itb` | `--_itb-focus-color` |
 
 ### When to Use Each Type
 
@@ -1492,7 +1503,6 @@ All component-scoped CSS custom properties MUST use the `--_[abbrev]-*` naming p
   /* Component-scoped properties - internal, calculated */
   --_cta-hover-bg: /* calculated by blend utilities */;
   --_cta-pressed-bg: /* calculated by blend utilities */;
-  --_cta-disabled-bg: /* calculated by blend utilities */;
 }
 
 .button-cta {

package/governance/Component-Development-Standards.md

@@ -13,7 +13,7 @@ description: Step-by-step guidelines for creating new component families in the
 **Scope**: cross-project
 **Layer**: 2
 **Relevant Tasks**: component-development, architecture, spec-planning
-**Last Reviewed**: 2026-01-02
+**Last Reviewed**: 2026-07-05
 
 ---
 
@@ -1121,7 +1121,7 @@ test_integration:
 #### Completion Documentation
 
 1. **Create Summary Document**: `docs/specs/[spec-name]/task-N-summary.md`
-2. **Commit Changes**: `./.kiro/hooks/commit-task.sh "Task N Complete: Description"` (runs release analysis automatically)
+2. **Open the Task PR**: `./.kiro/hooks/complete-task.sh "Task N Complete: Description (<spec>)"` — complete at merge; release analysis runs post-merge on `main`
 
 #### Version Impact
 

package/governance/Component-Family-Avatar.md

@@ -2,7 +2,6 @@
 id: component-family-avatar
 inclusion: manual
 name: Component-Family-Avatar
-aliases: avatar family work
 description: Avatar component family — identity representation with shape-based entity differentiation (circle for humans, hexagon for AI agents), image support with loading states and fallback. Load when working with avatar components, identity representation, or user/agent visual differentiation.
 ---