@3fn/core 13.0.0 → 14.0.0

package/mcp-server/src/query/__tests__/find-docs-calibration.test.ts

@@ -28,9 +28,7 @@
  * | concept query          | must include                           | expected tier |
  * |------------------------|----------------------------------------|---------------|
  * | "RTL"                  | Web-Authoring-Standards.md             | strong        |
- * |                        | Component-Family-Form-Inputs.md        | strong        |
  * | "internationalization" | Web-Authoring-Standards.md             | strong        |
- * |                        | Component-Family-Form-Inputs.md        | strong        |
  * | "spec planning"        | Process-Spec-Planning.md               | strong        |
  * | "EARS"                 | Process-Spec-Planning.md               | strong        |
  * | incidental-token case  | only incidental match                  | partial       |
@@ -60,7 +58,6 @@ const STEERING_DIR = path.resolve(__dirname, '../../../../governance');
  * absolute-path prefixes do not make the fixture brittle to CWD differences).
  */
 const RTL_DOC_A = 'Web-Authoring-Standards.md';
-const RTL_DOC_B = 'Component-Family-Form-Inputs.md';
 const SPEC_PLANNING_DOC = 'Process-Spec-Planning.md';
 
 // ---------------------------------------------------------------------------
@@ -132,7 +129,16 @@ describe('find_docs calibration fixtures — real corpus, tool boundary (Task 4.
   // Fixture 1 — RTL / right-to-left
   // -------------------------------------------------------------------------
 
-  describe('fixture: "RTL" → Web-Authoring-Standards.md + Component-Family-Form-Inputs.md (strong via aliases)', () => {
+  describe('fixture: "RTL" → Web-Authoring-Standards.md (strong via aliases)', () => {
+    /**
+     * NOTE (119-B Task 4 alias prune, 2026-08-02): Component-Family-Form-Inputs.md
+     * previously carried the same RTL alias set as a second calibration fixture
+     * (Spec 121 Task 5). Its only RTL content was two passing bullets, so the
+     * aliases were replaced with form-inputs-scoped vocabulary (Lina's domain
+     * ruling). The RTL/internationalization recall floor is satisfied by
+     * Web-Authoring-Standards.md alone, which has real RTL/logical-properties
+     * content and keeps its aliases.
+     */
     let result: FindDocsHandlerResult;
 
     beforeAll(() => {
@@ -155,26 +161,11 @@ describe('find_docs calibration fixtures — real corpus, tool boundary (Task 4.
       expect(entry!.matchConfidence).toBe('strong');
     });
 
-    it('includes Component-Family-Form-Inputs.md', () => {
-      const entry = findEntry(result, RTL_DOC_B);
-      expect(entry).toBeDefined();
-    });
-
-    it('classifies Component-Family-Form-Inputs.md as strong (aliases high-signal hit)', () => {
-      const entry = findEntry(result, RTL_DOC_B);
-      expect(entry!.matchConfidence).toBe('strong');
-    });
-
     it('emits three distinct Layer fields on Web-Authoring-Standards.md (criterion b)', () => {
       const entry = findEntry(result, RTL_DOC_A);
       assertThreeDistinctLayers(entry!);
     });
 
-    it('emits three distinct Layer fields on Component-Family-Form-Inputs.md (criterion b)', () => {
-      const entry = findEntry(result, RTL_DOC_B);
-      assertThreeDistinctLayers(entry!);
-    });
-
     it('matchedOn for the aliases hit contains "aliases:rtl" (auditable evidence)', () => {
       const entry = findEntry(result, RTL_DOC_A);
       // aliases are high-signal; the token "rtl" must appear in matchedOn as an aliases hit
@@ -186,7 +177,7 @@ describe('find_docs calibration fixtures — real corpus, tool boundary (Task 4.
   // Fixture 2 — internationalization
   // -------------------------------------------------------------------------
 
-  describe('fixture: "internationalization" → same two docs (strong)', () => {
+  describe('fixture: "internationalization" → Web-Authoring-Standards.md (strong)', () => {
     let result: FindDocsHandlerResult;
 
     beforeAll(() => {
@@ -199,12 +190,6 @@ describe('find_docs calibration fixtures — real corpus, tool boundary (Task 4.
       expect(entry!.matchConfidence).toBe('strong');
     });
 
-    it('includes Component-Family-Form-Inputs.md at strong', () => {
-      const entry = findEntry(result, RTL_DOC_B);
-      expect(entry).toBeDefined();
-      expect(entry!.matchConfidence).toBe('strong');
-    });
-
     it('emits three distinct Layer fields (criterion b)', () => {
       const entry = findEntry(result, RTL_DOC_A);
       assertThreeDistinctLayers(entry!);

package/mcp-server/src/relocation-integrity-gate/__tests__/relocation-integrity-gate.test.ts

@@ -19,9 +19,12 @@ import {
   assertMustFixCouplings,
   assertScope,
   runRelocationIntegrityGate,
+  scanPromptReferences,
   LOCKED_IDENTITY_IDS,
   DEFAULT_PROJECT_ROOT,
+  DEFAULT_GOVERNANCE_DIR,
 } from '../relocation-integrity-gate';
+import { DocumentIndexer } from '../../indexer/DocumentIndexer';
 
 describe('classifyReference — identity vs served vs template (Req 8 AC5)', () => {
   it('classifies a placeholder path-shape as template', () => {
@@ -198,20 +201,84 @@ describe('runRelocationIntegrityGate — full gate (the 119-A exit check, Req 8
     expect(result.unresolved).toEqual([]);
   });
 
-  it('resolves every served prompt ref via the legacy-fallback (Req 8 AC1–AC3)', async () => {
+  it('resolves a served prompt ref via legacy-fallback — fixture prompt (Req 8 AC1–AC3)', async () => {
+    // Anti-vacuity moved OFF live data (2026-07-11, Spec 122 U6): the served floor
+    // (≥1 served `.kiro/steering/*.md` ref in the REAL agent prompts) died by progress —
+    // the 122 cutovers regenerate agent prompts into runtime-neutral MCP-cue form, removing
+    // `.kiro/steering/*.md` file references. With Leonardo (U6) cut over, ZERO live prompts
+    // carry served refs (same class as the template floor's death at U3). The served-
+    // resolution behavior is now exercised NON-VACUOUSLY against a fixture prompt carrying a
+    // real relocated-doc ref, resolved through a real indexer (frozen legacy manifest seeded);
+    // the live leg below keeps the every-served-ref-resolves invariant without an inventory floor.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rig-served-'));
+    const indexer = new DocumentIndexer();
+    await indexer.indexDirectory(DEFAULT_GOVERNANCE_DIR); // seeds the frozen legacy manifest at its tail
+    try {
+      fs.mkdirSync(path.join(root, '.kiro/agents'), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, '.kiro/agents', 'fixture-prompt.md'),
+        '# Fixture\n\nSee `get_section({ path: ".kiro/steering/Token-Governance.md", heading: "Token Usage Governance" })`.\n',
+      );
+      const scan = scanPromptReferences(root, indexer);
+      const served = scan.references.filter((r) => r.role === 'served');
+      expect(served.length).toBeGreaterThanOrEqual(1);
+      expect(served.every((r) => r.resolved)).toBe(true);
+      expect(served.every((r) => r.strategy === 'legacy-fallback')).toBe(true);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('live prompts: every served ref (if any) resolves via legacy-fallback (Req 8 AC1–AC3)', async () => {
     const result = await runRelocationIntegrityGate();
     const served = result.references.filter((r) => r.role === 'served');
-    expect(served.length).toBeGreaterThan(0);
+    // NO count floor: the live corpus legitimately holds zero served refs since U6 (the
+    // fixture leg above covers non-vacuous resolution). If any served refs exist, each must
+    // resolve via legacy-fallback; the resolutionMechanism description holds regardless.
     expect(served.every((r) => r.resolved)).toBe(true);
     expect(served.every((r) => r.strategy === 'legacy-fallback')).toBe(true);
     expect(result.resolutionMechanism).toMatch(/legacy-fallback/);
   });
 
-  it('excludes template placeholders from pass/fail (Req 8 AC1 — not real refs)', async () => {
+  it('excludes template placeholders from pass/fail — fixture prompt (Req 8 AC1 — not real refs)', () => {
+    // Anti-vacuity moved OFF live data (2026-07-11, Spec 122 U3): the live floor
+    // (≥1 template in the real prompts) died by progress — Ada's U2 regeneration dropped
+    // `Token-Family-{Name}.md` (3 → 2) and Lina's U3 regeneration removed the corpus's
+    // LAST template placeholders (`Component-Family-{Name}.md` / `{FamilyName}`, 2 → 0),
+    // exactly as this test's old comment predicted. The exclusion behavior is now
+    // exercised non-vacuously via the extracted reference-axis seam on a fixture prompt;
+    // the live leg below keeps the invariant without an inventory floor.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rig-tpl-'));
+    try {
+      fs.mkdirSync(path.join(root, '.kiro/agents'), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, '.kiro/agents', 'fixture-prompt.md'),
+        '# Fixture\n\nSee `get_document_summary({ path: ".kiro/steering/Component-Family-{Name}.md" })`.\n',
+      );
+      // A template-only scan must never touch the resolver — throwing stub proves it.
+      const neverCalled = {
+        resolveRef: (): never => {
+          throw new Error('resolveRef must not be called for a template placeholder');
+        },
+      };
+      const scan = scanPromptReferences(root, neverCalled);
+      const templates = scan.references.filter((r) => r.role === 'template');
+      expect(templates.length).toBe(1);
+      expect(templates[0].ref).toBe('.kiro/steering/Component-Family-{Name}.md');
+      expect(templates[0].resolved).toBe(false);
+      // a template ref must never appear in unresolved — the exclusion under test
+      expect(scan.unresolved).toEqual([]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('live prompts: any template placeholder stays excluded from unresolved (Req 8 AC1)', async () => {
     const result = await runRelocationIntegrityGate();
     const templates = result.references.filter((r) => r.role === 'template');
-    expect(templates.length).toBe(3);
-    // a template ref must never appear in unresolved
+    // NO count floor: the live corpus legitimately holds zero placeholders since U3
+    // (see the fixture leg above for the non-vacuous exclusion assertion; the classifier
+    // routing itself is directly covered by the classifyReference tests).
     for (const t of templates) {
       expect(result.unresolved.some((u) => u.includes(t.ref))).toBe(false);
     }

package/mcp-server/src/relocation-integrity-gate/relocation-integrity-gate.ts

@@ -269,14 +269,44 @@ export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
   // non-identity .kiro/steering/ doc remains referenced in any agent JSON.
   {
     const dir = path.join(projectRoot, '.kiro/agents');
-    const jsons = fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+    const jsons = fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.json') && !f.endsWith('.attribution.json'))
+      .sort();
+
+    // Spec 122 cutover-ledger awareness (added at Ada's cutover, U2/PR #55): a GENERATED
+    // config carries only its designed ambient members — Ada's trim took the fleet total
+    // from 122 to 100 governance/ entries and broke the old flat `govEntries >= 120`
+    // floor, and every later cutover would break any fixed total again. The floor's real
+    // job is anti-vacuity over the HAND-maintained configs (proof the scan actually saw
+    // the remediated entries), so it is now PER-CONFIG (≥5 governance/ entries each; the
+    // thinnest hand config today carries 9) over NON-ledger configs only. Generated
+    // configs are exempt from the floor — their ref integrity is the generator gate's job
+    // (122-sweep-1-refs + 122-canonical-vs-truth) — but they stay IN the stray-relocating
+    // scan below: no config, hand or generated, may point a relocating doc at
+    // .kiro/steering/. When the ledger covers every seat, the floor leg is vacuously true
+    // and this gate's remediation duty is fully handed to the generation-era checks.
+    let ledgerAgents = new Set<string>();
+    try {
+      const ledgerText = fs.readFileSync(path.join(projectRoot, 'canonical/cutover-ledger.yaml'), 'utf-8');
+      ledgerAgents = new Set([...ledgerText.matchAll(/^\s*-\s*([a-z0-9-]+)\s*$/gm)].map((m) => m[1]));
+    } catch {
+      ledgerAgents = new Set(); // pre-122 tree: floor applies to all configs, as before
+    }
+
     let govEntries = 0;
+    const thinHandConfigs: string[] = [];
     const strayRelocating = new Set<string>();
     let strayIdentityLeak = false; // an .kiro/steering/ entry that is NOT an identity doc
     for (const j of jsons) {
       const content = fs.readFileSync(path.join(dir, j), 'utf-8');
+      const agentName = j.replace(/\.json$/, '');
       const govRe = /(?:file|skill):\/\/[^"]*governance\/[^"]*\.md/g;
-      govEntries += (content.match(govRe) || []).length;
+      const configGovEntries = (content.match(govRe) || []).length;
+      govEntries += configGovEntries;
+      if (!ledgerAgents.has(agentName) && configGovEntries < 5) {
+        thinHandConfigs.push(`${j} (${configGovEntries})`);
+      }
       const steerRe = /(?:file|skill):\/\/[^"]*\.kiro\/steering\/([^"/]+\.md)/g;
       let mm: RegExpExecArray | null;
       while ((mm = steerRe.exec(content)) !== null) {
@@ -287,13 +317,13 @@ export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
         }
       }
     }
-    const ok = govEntries >= 120 && !strayIdentityLeak;
+    const ok = thinHandConfigs.length === 0 && !strayIdentityLeak;
     checks.push({
       surface: 'agent-definition resources[] (file:// + skill://)',
       remediated: ok,
       detail: ok
-        ? `governance/ entries=${govEntries} (≥120); zero relocating docs left at .kiro/steering/`
-        : `governance/ entries=${govEntries}; UNREMEDIATED relocating docs still at .kiro/steering/: ${[...strayRelocating].join(', ')}`,
+        ? `governance/ entries=${govEntries} (per-hand-config floor ≥5 held; ${ledgerAgents.size} generator-governed config(s) exempt); zero relocating docs left at .kiro/steering/`
+        : `governance/ entries=${govEntries}; hand configs under the ≥5 floor: ${thinHandConfigs.join(', ') || 'none'}; UNREMEDIATED relocating docs still at .kiro/steering/: ${[...strayRelocating].join(', ')}`,
     });
   }
 
@@ -511,27 +541,28 @@ export interface GateOptions {
   indexer?: DocumentIndexer;
 }
 
+/** The reference axis's scan output — see {@link scanPromptReferences}. */
+export interface PromptReferenceScan {
+  references: ReferenceCheck[];
+  unresolved: string[];
+  referencedIdentityIds: Set<string>;
+}
+
 /**
- * Run the relocation-integrity gate (the 119-A exit check).
- *
- * Builds a real `DocumentIndexer` over `governance/` (the frozen legacy manifest is
- * seeded automatically at the tail of `indexDirectory`), then exercises the live
- * `resolveRef` per prompt reference. Identity refs bypass MCP (static presence);
- * must-fix couplings + family-guidance + scope are asserted statically.
+ * The reference axis (Req 8 AC1–AC5), extracted from the orchestrator as its own
+ * exported seam: scan every prompt under `projectRoot`, classify each steering ref
+ * (template / identity / served), and resolve served refs through the live indexer.
+ * Template placeholders are excluded from pass/fail here — they are recorded but
+ * NEVER pushed to `unresolved` — which is the behavior the fixture-based unit test
+ * exercises directly (the live corpus carries zero placeholders since the Spec 122
+ * U3 regeneration, so full-gate runs can no longer test this leg non-vacuously).
+ * Only served refs touch the indexer; a template-only or identity-only scan never
+ * calls `resolveRef`.
  */
-export async function runRelocationIntegrityGate(opts: GateOptions = {}): Promise<GateResult> {
-  const projectRoot = opts.projectRoot ?? DEFAULT_PROJECT_ROOT;
-  const governanceDir = opts.governanceDir ?? DEFAULT_GOVERNANCE_DIR;
-
-  let indexer = opts.indexer;
-  if (!indexer) {
-    indexer = new DocumentIndexer();
-    // indexDirectory seeds the frozen legacy manifest at its tail (re-seed
-    // obligation) — so the legacy-fallback resolution mechanism is live here.
-    await indexer.indexDirectory(governanceDir);
-  }
-
-  // --- Reference axis (Req 8 AC1–AC5) ---
+export function scanPromptReferences(
+  projectRoot: string,
+  indexer: Pick<DocumentIndexer, 'resolveRef'>
+): PromptReferenceScan {
   const references: ReferenceCheck[] = [];
   const unresolved: string[] = [];
   const referencedIdentityIds = new Set<string>();
@@ -583,6 +614,32 @@ export async function runRelocationIntegrityGate(opts: GateOptions = {}): Promis
     }
   }
 
+  return { references, unresolved, referencedIdentityIds };
+}
+
+/**
+ * Run the relocation-integrity gate (the 119-A exit check).
+ *
+ * Builds a real `DocumentIndexer` over `governance/` (the frozen legacy manifest is
+ * seeded automatically at the tail of `indexDirectory`), then exercises the live
+ * `resolveRef` per prompt reference. Identity refs bypass MCP (static presence);
+ * must-fix couplings + family-guidance + scope are asserted statically.
+ */
+export async function runRelocationIntegrityGate(opts: GateOptions = {}): Promise<GateResult> {
+  const projectRoot = opts.projectRoot ?? DEFAULT_PROJECT_ROOT;
+  const governanceDir = opts.governanceDir ?? DEFAULT_GOVERNANCE_DIR;
+
+  let indexer = opts.indexer;
+  if (!indexer) {
+    indexer = new DocumentIndexer();
+    // indexDirectory seeds the frozen legacy manifest at its tail (re-seed
+    // obligation) — so the legacy-fallback resolution mechanism is live here.
+    await indexer.indexDirectory(governanceDir);
+  }
+
+  // --- Reference axis (Req 8 AC1–AC5) ---
+  const { references, unresolved, referencedIdentityIds } = scanPromptReferences(projectRoot, indexer);
+
   // --- Identity axis (Req 8 AC5) ---
   const identity = assertIdentityPresence(projectRoot, referencedIdentityIds);
   for (const c of identity) {

package/mcp-server/src/tools/list-cross-references.ts

@@ -16,13 +16,13 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const 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 — doc id, then indexed relative path, then legacy `.kiro/steering/…` path.',
   inputSchema: {
     type: 'object' as const,
     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/…` path — same resolver chain as get_document_summary'
       }
     },
     required: ['path'] as string[]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3fn/core",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "True Native cross-platform design system with mathematical foundations",
   "license": "Apache-2.0",
   "author": "Peter Michaels Allen",
@@ -42,42 +42,42 @@
   ],
   "exports": {
     ".": {
-      "import": "./dist/browser/designerpunk.esm.js",
-      "types": "./dist/browser-entry.d.ts"
+      "types": "./dist/browser-entry.d.ts",
+      "import": "./dist/browser/designerpunk.esm.js"
     },
     "./components": {
-      "import": "./dist/browser/designerpunk.esm.js",
-      "types": "./dist/browser-entry.d.ts"
+      "types": "./dist/browser-entry.d.ts",
+      "import": "./dist/browser/designerpunk.esm.js"
     },
     "./tokens.css": "./dist/DesignTokens.web.css",
     "./component-tokens.css": "./dist/ComponentTokens.web.css",
     "./config": {
+      "types": "./dist/config/index.d.ts",
       "import": "./dist/config/index.js",
-      "require": "./dist/config/index.js",
-      "types": "./dist/config/index.d.ts"
+      "require": "./dist/config/index.js"
     },
     "./types": {
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/types/index.js",
-      "require": "./dist/types/index.js",
-      "types": "./dist/types/index.d.ts"
+      "require": "./dist/types/index.js"
     },
     "./build": {
+      "types": "./dist/build/tokens/index.d.ts",
       "import": "./dist/build/tokens/index.js",
-      "require": "./dist/build/tokens/index.js",
-      "types": "./dist/build/tokens/index.d.ts"
+      "require": "./dist/build/tokens/index.js"
     },
     "./blend": {
+      "types": "./dist/blend/index.d.ts",
       "import": "./dist/blend/index.js",
-      "require": "./dist/blend/index.js",
-      "types": "./dist/blend/index.d.ts"
+      "require": "./dist/blend/index.js"
     },
     "./jest-preset": {
       "require": "./dist/testing/jest-preset.js"
     },
     "./testing": {
+      "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js",
-      "require": "./dist/testing/index.js",
-      "types": "./dist/testing/index.d.ts"
+      "require": "./dist/testing/index.js"
     },
     "./grid.css": "./src/styles/responsive-grid.css",
     "./fonts/inter.css": "./src/assets/fonts/inter/inter.css",
@@ -106,15 +106,15 @@
     "build:verify": "node verify-build.js",
     "build:validate": "npx tsx src/validators/buildValidation.ts",
     "lint": "eslint 'src/components/**/*.ts' 'src/components/**/*.tsx' --no-error-on-unmatched-pattern",
-    "test": "jest --testPathIgnorePatterns='performance/__tests__|__tests__/performance|PerformanceValidation'",
+    "test": "jest --config jest.functional.config.js",
     "test:all": "jest",
+    "test:agent-generator": "jest --config tools/agent-generator/jest.config.js",
     "test:consumer": "jest --roots='<rootDir>/tests' --testMatch='**/consumer-integration.test.ts' --runInBand --testTimeout=120000 --forceExit",
     "test:resolution-matrix": "node src/config/__resolution-matrix__/run-matrix.js",
     "test:performance": "jest --testPathPatterns='performance/__tests__|__tests__/performance'",
     "test:performance:isolated": "jest --config jest.performance.config.js --runInBand",
-    "test:quick": "jest --testPathIgnorePatterns='(performance|integration)'",
-    "test:watch": "jest --watch --testPathIgnorePatterns='performance/__tests__|__tests__/performance'",
-    "test:coverage": "jest --coverage --testPathIgnorePatterns='performance/__tests__|__tests__/performance'",
+    "test:watch": "jest --watch --config jest.functional.config.js",
+    "test:coverage": "jest --coverage --config jest.functional.config.js",
     "release:analyze": "npx tsx src/tools/release/cli/release-tool.ts analyze",
     "release:notes": "npx tsx src/tools/release/cli/release-tool.ts notes",
     "release:run": "npx tsx src/tools/release/cli/release-tool.ts release",
@@ -122,6 +122,7 @@
     "diagnose:release-issues": "node scripts/diagnose-release-issues.js",
     "audit:tokens": "node scripts/audit-component-tokens.js",
     "audit:tokens:detailed": "node scripts/audit-component-tokens.js -- --detailed",
+    "audit:coverage-map": "npx tsx tools/agent-generator/coverage-map.ts",
     "audit:mode-parity": "npx tsx src/validators/ModeParity.ts",
     "audit:theme-drift": "npx tsx src/tools/ThemeFileGenerator.ts > /tmp/theme-skeleton-check.ts && diff -u src/tokens/themes/dark/SemanticOverrides.ts /tmp/theme-skeleton-check.ts || echo '⚠️  Theme file drift detected — regenerate with: npm run generate:theme-skeleton'",
     "generate:theme-skeleton": "npx tsx src/tools/ThemeFileGenerator.ts",
@@ -133,8 +134,9 @@
     "check:drift": "node scripts/check-package-name-drift.js",
     "check:id-uniqueness": "tsx scripts/check-id-uniqueness.ts",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm run check:drift",
-    "postpublish": "git diff --quiet token-index/ || (git add token-index/ && git commit -m 'Regenerate token-index (post-publish)' && git push origin main)"
+    "verify:token-index-clean": "git diff --quiet token-index/ || (echo '✖ token-index/ is stale relative to the committed state. Regenerate and commit it on the RELEASE BRANCH (it traverses the PR gate with the version bump) before publishing. See .kiro/hooks/RELEASE-FLOW.md.' && exit 1)",
+    "prepublishOnly": "npm run build && npm run check:drift && npm run verify:token-index-clean",
+    "postpublish": "git diff --quiet token-index/ || echo '⚠️  token-index/ changed during publish — commit it via a PR (main is branch-protected; never push it directly). See .kiro/hooks/RELEASE-FLOW.md.'"
   },
   "devDependencies": {
     "@types/glob": "^8.1.0",

package/src/__tests__/browser-distribution/css-bundling.test.ts

@@ -183,11 +183,13 @@ describe('CSS Bundling for Browser Distribution', () => {
       expect(bundleContent).toMatch(/:hover/);
     });
 
-    it('should contain disabled state styles', () => {
+    it('should not contain disabled state styles (no-disabled-states philosophy)', () => {
       const bundleContent = fs.readFileSync(ESM_BUNDLE_PATH, 'utf-8');
-      
-      // Components should have disabled styles
-      expect(bundleContent).toMatch(/:disabled|--disabled/);
+
+      // DesignerPunk does not support disabled states: if an action is
+      // unavailable, the component should not be rendered. No component CSS
+      // should ship disabled selectors or modifier classes.
+      expect(bundleContent).not.toMatch(/:disabled|--disabled/);
     });
   });
 

package/src/__tests__/console-allowlist.json

@@ -0,0 +1,14 @@
+[
+  { "suite": "src/components/core/Avatar-Base/__tests__/Avatar.accessibility.test.ts", "pattern": "^AvatarBaseElement: \"alt\" is required when \"src\" is provided\\.", "reason": "Spec 126 (O2, ratified 2026-07-09) resolved the original Req 5.4 / Req 9.2 tension this entry was seeded against: the warn condition is now `type === 'human' && src && alt == null && !decorative`, so a genuinely decorative or empty-alt (via setAttribute) fixture no longer warns at all. This entry is retained as a safety net, not a live suppression path — every fixture in this suite that legitimately triggers the warn (human + src + absent alt, incl. the property-form alt='' collapse) wraps it in a local jest.spyOn(console,'warn').mockImplementation(() => {}), which per console-fail-setup.ts's documented shadow behavior fully swallows the output before this hook ever sees it. Pattern updated to match the new Spec 126 message string (was: '\"alt\" prop is required when \"src\" is provided')." },
+  { "suite": "src/components/core/Chip-Base/__tests__/ChipBase.test.ts", "pattern": "^ChipBase: Could not calculate blend colors", "reason": "jsdom stylesheet limitation: jsdom never applies real CSS, so the blend-color token lookup cannot succeed and the component's designed CSS-fallback warn fires every run (fired async via rAF). PR #39 adjudicated as environmental noise, not a defect. Component-prefixed pattern (Lina review, PR #39) — a bare 'Could not calculate blend colors' substring is shared by Button components too; prefix-matching prevents accidentally swallowing a cross-component warn. Discharges the pending jsdom-stylesheet-limitation doc-addition (125-B-backlog.md item 5; Thurgood chip, 2026-07-09)." },
+  { "suite": "src/components/core/Chip-Filter/__tests__/ChipFilter.test.ts", "pattern": "^ChipFilter: Could not calculate blend colors", "reason": "jsdom stylesheet limitation: jsdom never applies real CSS, so the blend-color token lookup cannot succeed and the component's designed CSS-fallback warn fires every run (fired async via rAF). PR #39 adjudicated as environmental noise, not a defect. Component-prefixed pattern (Lina review, PR #39) — a bare 'Could not calculate blend colors' substring is shared by Button components too; prefix-matching prevents accidentally swallowing a cross-component warn. Discharges the pending jsdom-stylesheet-limitation doc-addition (125-B-backlog.md item 5; Thurgood chip, 2026-07-09)." },
+  { "suite": "src/components/core/Chip-Input/__tests__/ChipInput.test.ts", "pattern": "^ChipInput: Could not calculate blend colors", "reason": "jsdom stylesheet limitation: jsdom never applies real CSS, so the blend-color token lookup cannot succeed and the component's designed CSS-fallback warn fires every run (fired async via rAF). PR #39 adjudicated as environmental noise, not a defect. Component-prefixed pattern (Lina review, PR #39) — a bare 'Could not calculate blend colors' substring is shared by Button components too; prefix-matching prevents accidentally swallowing a cross-component warn. Discharges the pending jsdom-stylesheet-limitation doc-addition (125-B-backlog.md item 5; Thurgood chip, 2026-07-09)." },
+  { "suite": "src/build/errors/__tests__/ErrorHandler.test.ts", "pattern": "^\\[(ERROR|WARNING|INFO)\\]|^Suggestions:|^ {2}\\u2022 |^ {2}\\.\\.\\. and \\d+ more", "reason": "Deliberate error-path logging: this suite constructs BuildErrors with fake TEST_ERROR/CONFIG_ERROR/BUILD_ERROR codes specifically to assert ErrorHandler's own console-emitting default logger (ErrorHandler.ts defaultLogger/formatErrorMessage) — the console output IS the behavior under test. PR #39 adjudicated as expected noise (96 error blocks silenced fleet-wide, this suite's share among them)." },
+  { "suite": "src/build/errors/__tests__/ErrorHandler.integration.test.ts", "pattern": "^\\[(ERROR|WARNING|INFO)\\]|^Suggestions:|^ {2}\\u2022 |^ {2}\\.\\.\\. and \\d+ more", "reason": "Deliberate error-path logging: this suite exercises ErrorHandler/ErrorReporter integration with fake BUILD_ERROR/CONFIG_ERROR codes — the console output IS the behavior under test. PR #39 adjudicated as expected noise." },
+  { "suite": "product-mcp-server/src/__tests__/GapDetector.test.ts", "pattern": "^\\[mcp-product-server\\] Component directory not found: .* \\u2014 gap detection disabled$", "reason": "Deliberate error-path logging: the 'with missing component directory' tests intentionally point GapDetector at a nonexistent path to assert its disabled-gracefully behavior — the console.error IS the assertion target for the first test and expected repeat noise for the others in the same describe block. PR #39 adjudicated as expected." },
+  { "suite": "product-mcp-server/src/__tests__/ProductIndexerWalk.test.ts", "pattern": "^\\[mcp-product-server\\] Indexed: \\d+ screens, \\d+ domain objects, \\d+ templates, \\d+ one-off components$", "reason": "ProductIndexer.index() logs an informational indexing summary via console.error (not a failure signal) on every index() call. PR #39 adjudicated as expected per-run noise, silenced via a beforeAll spy in this suite." },
+  { "suite": "product-mcp-server/src/__tests__/Spec108-ProductTokens.test.ts", "pattern": "^\\[mcp-product-server\\] Indexed: \\d+ screens, \\d+ domain objects, \\d+ templates, \\d+ one-off components$", "reason": "ProductIndexer.index() logs an informational indexing summary via console.error (not a failure signal) on every index() call. PR #39 adjudicated as expected per-run noise, silenced via a beforeAll spy in this suite." },
+  { "suite": "src/__tests__/integration/Spec107-DesignLanguageContext.test.ts", "pattern": "^\\[mcp-product-server\\] Indexed: \\d+ screens, \\d+ domain objects, \\d+ templates, \\d+ one-off components$", "reason": "ProductIndexer.index() logs an informational indexing summary via console.error (not a failure signal); this suite's ProductIndexer instances are constructed inside nested beforeAll hooks, so PR #39 installed the spy in an outer beforeAll (not beforeEach) to be active before them. Adjudicated as expected noise." },
+  { "suite": "src/cli/__tests__/figma-extract.test.ts", "pattern": "^\\u274c |^Usage: npm run figma:extract|^\\s+npm run figma:extract|^\\s+Run the DTCG generator first|^$", "reason": "Genuinely novel class, adjudicated in this task (125-B Task 4.4, not part of PR #39): figma-extract is a CLI tool whose console.error output IS its product surface — every message this suite asserts on is the deliberate, deterministic error/usage text figma-extract.ts emits (arg validation, DTCG-load failures, extraction failures, usage banners, blank-line separators). This suite installs its own module-top-level console.error spy (mockConsoleError, restored per-file, not per-test) and reads its .mock.calls directly; this hook's beforeEach captures the CURRENT console.error before spying and calls through to it, so the suite's own assertions keep working unaffected." },
+  { "suite": "src/cli/__tests__/figma-push.test.ts", "pattern": "^\\u274c |^Resolution:|^\\s+\\d+\\.\\s|^\\s+-\\s|^\\s+Run the DTCG generator first|^$", "reason": "Genuinely novel class, adjudicated in this task (125-B Task 4.4, not part of PR #39): figma-push is a CLI tool whose console.error output IS its product surface — every message this suite asserts on is the deliberate, deterministic error/resolution text figma-push.ts emits (arg validation, DTCG-load failures, drift/sync-failure reporting with its numbered resolution steps and '  - <detail>' lists, blank-line separators). Same module-top-level console.error spy pattern as figma-extract.test.ts; this hook chains through to it rather than shadowing it." }
+]