@3fn/core 13.0.0 → 14.1.0

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.1.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,22 +106,18 @@
     "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'",
-    "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",
-    "validate:release-setup": "node scripts/validate-release-setup.js",
-    "diagnose:release-issues": "node scripts/diagnose-release-issues.js",
+    "test:watch": "jest --watch --config jest.functional.config.js",
+    "test:coverage": "jest --coverage --config jest.functional.config.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",
@@ -132,9 +128,11 @@
     "figma:generate-component": "npx tsx scripts/figma-component-generator.ts",
     "check:drift": "node scripts/check-package-name-drift.js",
     "check:id-uniqueness": "tsx scripts/check-id-uniqueness.ts",
+    "check:section-citations": "tsx scripts/check-section-citations.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." }
+]

package/src/__tests__/console-fail-setup.ts

@@ -0,0 +1,169 @@
+/**
+ * Console-fail hook (125-B, Requirement 11 / Design C8).
+ *
+ * Captures console.error/console.warn per test and FAILS the test when
+ * unallowlisted output is produced. Checked against the checked-in
+ * allowlist (`src/__tests__/console-allowlist.json`, a (suite × message-pattern)
+ * grain — see that file for entries + reasons, and
+ * governance/classification-map.md § "console-fail-root-lanes" for the rule
+ * this hook enforces).
+ *
+ * SCOPE — root functional lanes ONLY (wired via the root jest.config.js's
+ * `setupFilesAfterEnv`). Sub-package suites (mcp-server, application-mcp-server
+ * — own jest 29 configs outside this repo's root `roots`) are NOT covered by
+ * this hook; see governance/classification-map.md
+ * § "console-fail-subpackage-deferred" for the recorded deferral.
+ * `product-mcp-server/src/**` IS covered — it lives inside root `roots`.
+ *
+ * VERSION-AGNOSTIC BY DESIGN (125-B C8 constraint, recorded for any future
+ * sub-package replication): plain `jest.spyOn` / method-swap capture only —
+ * no jest-30-only API. Stable on jest 29 and jest 30.
+ *
+ * Known limitation (recorded, not solved here): suites that install their
+ * OWN console.error/warn spy on top of this hook's (26 files predate this
+ * hook — "house style", nested `describe`-level `beforeEach`, which runs
+ * AFTER this hook's root-level `beforeEach`) shadow this hook for the
+ * duration of their own mock. Output fully swallowed by a local mock's
+ * `mockImplementation(() => {})` never reaches this hook (nothing to check
+ * — correct no-op). Output a local mock passes through (e.g. Chip's
+ * "anything else passes through" pattern) DOES reach this hook via the
+ * bound reference the local suite captured. Because this hook is a plain
+ * property swap rather than a `jest.spyOn` mock (see below), a local
+ * suite's own `jest.restoreAllMocks()` restores only ITS OWN jest-tracked
+ * spy — never this hook's swap, which isn't in Jest's mock registry at all.
+ * The residual edge case is narrower than a spyOn-based hook would have:
+ * async/deferred output (e.g. an rAF-queued warn) that fires after this
+ * test's `afterEach` has already restored `console.error`/`console.warn`
+ * back to whatever was there before this test's `beforeEach` — a normal,
+ * expected end-of-test boundary, not a cross-hook interaction — can land on
+ * the real console unrecorded and unchecked. It does not produce false
+ * failures.
+ *
+ * Chain-through, not shadow (fixed during 4.4's own gate-bite run): the
+ * "before" console.error/warn reference is captured FRESH inside
+ * `beforeEach`, immediately before this hook installs itself — not once at
+ * module load. A handful of CLI suites (figma-extract.test.ts,
+ * figma-push.test.ts) install a PERSISTENT module-top-level console mock of
+ * their own (no per-test beforeEach/afterEach — restored once in `afterAll`,
+ * if at all) and assert against its `.mock.calls`. Capturing "before" once
+ * at this module's own load time would have bound to the pristine native
+ * console — permanently bypassing those suites' own mocks for every test
+ * and silently breaking their `consoleOutput()`-style assertions.
+ *
+ * PLAIN PROPERTY SWAP, NOT `jest.spyOn` (also fixed during 4.4's gate-bite
+ * run — the reason this hook does NOT use jest.spyOn even though the header
+ * above still calls the general technique "spyOn/method swap"): `jest.spyOn`
+ * has a documented reuse rule — spying on a property that is ALREADY a Jest
+ * mock function returns and mutates THAT SAME mock object rather than
+ * wrapping a new one. Against the figma-extract/figma-push suites'
+ * persistent console.error mock, that reuse rule made `jest.spyOn(console,
+ * 'error').mockImplementation(fn)` overwrite THEIR mock's implementation
+ * with `fn` — and this hook's own "before" reference, bound to that same
+ * mutable mock object, then called back into `fn` on every invocation:
+ * infinite recursion, observed as a stack overflow on the very first
+ * `console.error` call in a chained suite. A plain property assignment
+ * (`console.error = wrapper; ...; console.error = original;`) sidesteps
+ * Jest's mock-identity bookkeeping entirely — the same technique the header
+ * above documents as version-agnostic ("plain jest.spyOn / method swap"),
+ * using the method-swap half specifically because it composes safely with
+ * another suite's pre-existing mock, which spyOn's reuse rule does not.
+ */
+
+import allowlistData from './console-allowlist.json';
+import * as path from 'path';
+
+interface AllowlistEntry {
+  suite: string;
+  pattern: string;
+  reason: string;
+}
+
+const allowlist = allowlistData as AllowlistEntry[];
+
+function isAllowed(suite: string, message: string): boolean {
+  return allowlist.some((entry) => {
+    if (entry.suite !== suite) return false;
+    try {
+      return new RegExp(entry.pattern).test(message);
+    } catch {
+      // A malformed pattern never silently passes output through.
+      return false;
+    }
+  });
+}
+
+function stringifyArg(value: unknown): string {
+  if (value instanceof Error) return value.stack || value.message;
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function formatArgs(args: unknown[]): string {
+  return args.map(stringifyArg).join(' ');
+}
+
+function currentSuitePath(): string {
+  // expect.getState().testPath is the absolute path to the currently
+  // running test file. Repo root is resolved relative to THIS file
+  // (src/__tests__/), so it's correct regardless of process cwd.
+  const testPath = expect.getState().testPath;
+  if (!testPath) return '';
+  const repoRoot = path.resolve(__dirname, '..', '..');
+  return path.relative(repoRoot, testPath).split(path.sep).join('/');
+}
+
+interface CapturedOutput {
+  method: 'error' | 'warn';
+  message: string;
+}
+
+let captured: CapturedOutput[] = [];
+let originalError: typeof console.error | undefined;
+let originalWarn: typeof console.warn | undefined;
+
+beforeEach(() => {
+  captured = [];
+
+  // Capture whatever is CURRENTLY installed (native console, or another
+  // suite's own persistent mock) immediately before swapping — see the
+  // "Chain-through, not shadow" / "Plain property swap" header notes.
+  originalError = console.error;
+  originalWarn = console.warn;
+
+  console.error = (...args: unknown[]) => {
+    captured.push({ method: 'error', message: formatArgs(args) });
+    originalError!.apply(console, args);
+  };
+
+  console.warn = (...args: unknown[]) => {
+    captured.push({ method: 'warn', message: formatArgs(args) });
+    originalWarn!.apply(console, args);
+  };
+});
+
+afterEach(() => {
+  const suite = currentSuitePath();
+
+  // Targeted restore only — put back exactly what was there before this
+  // test's beforeEach ran (native console, or another suite's own mock).
+  if (originalError) console.error = originalError;
+  if (originalWarn) console.warn = originalWarn;
+
+  const unallowed = captured.filter((entry) => !isAllowed(suite, entry.message));
+  captured = [];
+
+  if (unallowed.length > 0) {
+    const details = unallowed
+      .map((entry) => `  [console.${entry.method}] ${entry.message}`)
+      .join('\n');
+    throw new Error(
+      `console-fail: unallowlisted console output in ${suite}:\n${details}\n\n` +
+        'Legitimate expected noise: add a { suite, pattern, reason } entry to ' +
+        'src/__tests__/console-allowlist.json. Genuine defect: fix the source.'
+    );
+  }
+});

package/src/__tests__/integration/Spec107-DesignLanguageContext.test.ts

@@ -16,6 +16,22 @@ const PHILOSOPHY_PATH = path.resolve(__dirname, '../../../design-language/design
 const PRODUCT_FIXTURES = path.resolve(__dirname, '../../../product-mcp-server/src/__tests__/fixtures');
 
 describe('Spec 107 Integration: Design Language Context', () => {
+  let consoleErrorSpy: jest.SpyInstance;
+
+  beforeAll(() => {
+    // ProductIndexer logs indexing summaries via console.error (informational, not a failure).
+    // Installed in beforeAll (not beforeEach) so it's active before nested beforeAll hooks
+    // that construct/index a ProductIndexer run.
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  beforeEach(() => {
+    consoleErrorSpy.mockClear();
+  });
 
   describe('Application MCP — Design Philosophy', () => {
     let indexer: any;