@3fn/core 14.0.0 → 15.0.0

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

@@ -172,7 +172,7 @@ describe('assertFamilyGuidance — top-level companion resolution (Req 8 AC6)',
 describe('assertMustFixCouplings — shape + naming (Req 8 AC7)', () => {
   it('produces one check per Bucket A surface, each with surface+remediated+detail', () => {
     const checks = assertMustFixCouplings(DEFAULT_PROJECT_ROOT);
-    expect(checks.length).toBe(7);
+    expect(checks.length).toBe(5);
     for (const c of checks) {
       expect(typeof c.surface).toBe('string');
       expect(typeof c.remediated).toBe('boolean');
@@ -290,10 +290,10 @@ describe('runRelocationIntegrityGate — full gate (the 119-A exit check, Req 8
     expect(result.summary.identityVerified).toBe(9);
   });
 
-  it('remediates all 7 must-fix coupling surfaces (Req 8 AC7)', async () => {
+  it('remediates all 5 standing must-fix coupling surfaces (A4/A7 retired 2026-10-01) (Req 8 AC7)', async () => {
     const result = await runRelocationIntegrityGate();
     expect(result.summary.couplingsRemediated).toBe(result.summary.couplingsTotal);
-    expect(result.summary.couplingsTotal).toBe(7);
+    expect(result.summary.couplingsTotal).toBe(5);
   });
 
   it('reports zero new family-guidance companion warnings (Req 8 AC6)', async () => {

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

@@ -15,8 +15,18 @@
  *      locked always-set + file exists at its `.kiro/steering/` path), NEVER via
  *      an MCP round-trip — identity docs are not in the governance-only index
  *      (Req 8 AC5 / Req 2 AC4).
- *   3. every MUST-FIX coupling surface (coupling-sweep Bucket A) is repointed to
- *      `governance/` and functional (Req 8 AC7).
+ *   3. every MUST-FIX coupling surface that this gate still holds (coupling-sweep
+ *      Bucket A) is repointed to `governance/` and functional (Req 8 AC7). Five
+ *      surfaces stand: A1, A2, A3, A5, A6. Legs A4 and A7 were RETIRED on 2026-10-01 by
+ *      Peter's ruling (`.kiro/issues/2026-10-01-relocation-integrity-gate-vs-123-install-shape.md`
+ *      § "Peter's ruling — RETIRE"; the three residuals moved, per his 2026-10-02 answer
+ *      "Move all three, and remove the legs") and REMOVED outright, so the count is
+ *      5, not 7: a leg left in the array that always reported `remediated: true` would be
+ *      a vacuous green. They asserted 119-A's copy-the-corpus MECHANISM, then (after the
+ *      2026-10-01 rewrite) the Spec 123 install shape; the install shape is now held by
+ *      named standing checks, per sub-check — see the doc comment on
+ *      `assertMustFixCouplings`. The 119-A exit gate remains 119-A's exit check over the
+ *      five surviving must-fix surfaces. 119-A's own closed records ("7/7") stay as written.
  *   4. relocation introduced ZERO new family-guidance companion-path warnings
  *      (Req 8 AC6) — asserted over the 9 top-level companions the FamilyGuidanceIndexer
  *      parses (the 13 nested are gate-blind: green ≠ all 22 verified).
@@ -241,9 +251,61 @@ function exists(projectRoot: string, rel: string): boolean {
 }
 
 /**
- * Assert every coupling-sweep Bucket A surface is repointed to `governance/` and
- * functional. Each check is intentionally specific (Req 8 AC4: no generic health
- * check) and names the surface on failure (Req 8 AC7).
+ * id → on-disk filename in `.kiro/steering/`, resolved by the frontmatter `id:` line.
+ * The single source for the identity axis (no second hardcoded list of identity filenames).
+ */
+function identityIdToFile(projectRoot: string): Map<string, string> {
+  const steeringDir = path.join(projectRoot, '.kiro/steering');
+  const files = fs.existsSync(steeringDir) ? fs.readdirSync(steeringDir) : [];
+  const idToFile = new Map<string, string>();
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    const content = fs.readFileSync(path.join(steeringDir, f), 'utf-8');
+    const m = content.match(/^id:\s*(.+)$/m);
+    if (m) idToFile.set(m[1].trim(), f);
+  }
+  return idToFile;
+}
+
+/**
+ * Assert every coupling-sweep Bucket A surface this gate still holds (A1, A2, A3, A5,
+ * A6) is repointed to `governance/` and functional. Each check is intentionally specific
+ * (Req 8 AC4: no generic health check) and names the surface on failure (Req 8 AC7).
+ *
+ * LEGS A4 AND A7 RETIRED 2026-10-01 (Peter's ruling, issue
+ * `2026-10-01-relocation-integrity-gate-vs-123-install-shape` § "Peter's ruling — RETIRE";
+ * residuals moved per his 2026-10-02 answer "Move all three, and remove the legs").
+ * They are removed, not left as always-green legs; the count is 5. Spec 123's install shape
+ * (U2b) made their source-shape assertions the wrong instrument; each sub-check is
+ * discharged by a named standing check, by output rather than by source shape:
+ *   A4.1 init copies no package corpus      -> src/cli/__tests__/init.test.ts "creates all
+ *        expected artifacts, and does NOT copy src/types or src/components/core" and "the
+ *        release-1 copy rows are gone: ..."; tests/consumer-integration.test.ts 16.6 "the
+ *        emitted agent-layer file set equals the guarded rendering ..." (exact set).
+ *   A4.2 init emits the agent layer         -> init.test.ts "init --target=%s emits exactly
+ *        the lane's file set for that target, ..."; the same 16.6 exact-set test.
+ *   A4.3 / A4.4 designerpunk.ts docs-MCP root (governance, never .kiro/steering)
+ *                                           -> tests/consumer-integration.test.ts "Docs MCP
+ *        returns documentation data" (driven through `designerpunk mcp:docs`; asserts the
+ *        CLI's and the server's data root = the installed package's `governance`, source
+ *        `env`, and a non-empty index)  [residual R1].
+ *   A7.1 / A7.2a files[] ships governance/ and each of the eight identity docs
+ *                                           -> the 16.6 block (exact-set / byte-equal vs the
+ *        guarded rendering; "Kiro: every agent resource resolves in the packed install ...").
+ *   A7.2b / A7.3 exactly eight identity docs, no steering glob, no personal note in files[]
+ *                                           -> tests/consumer-integration.test.ts describe
+ *        "Spec 123 R2 — the package ships exactly the eight identity docs and never the
+ *        personal note"  [residual R2].
+ *   A7.4a template MCP_STEERING_DIR = governance
+ *                                           -> init.test.ts, the Kiro and Claude Code
+ *        MCP-config cases (`MCP_STEERING_DIR` = './node_modules/@3fn/core/governance')
+ *        [residual R3].
+ *   A7.4b template has no dead tool         -> init.test.ts "Kiro: each server's autoApprove is
+ *        SET-EQUAL ..." and "Claude Code: .claude/settings.json permissions.allow is
+ *        SET-EQUAL ..."; 16.6 "the MCP config and approval keys are present ...".
+ *   A7.5 COPY_ROOTS holds the release-1 roots -> src/cli/__tests__/sync.cohort.test.ts
+ *        "COPY_ROOTS keeps the release-1 roots it recognizes (this test is the pin; the 119-A
+ *        gate leg A7 that also held it is retired)".
  */
 export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
   const checks: CouplingCheck[] = [];
@@ -340,21 +402,8 @@ export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
     });
   }
 
-  // A4: src/cli/init.ts (ADD governance copyDir, KEEP .kiro/steering) + designerpunk.ts (repoint)
-  {
-    const init = read(projectRoot, 'src/cli/init.ts');
-    const initGov = /copyDir\(\s*[^)]*['"`][^'"`]*governance['"`]/.test(init);
-    const initKeepsSteering = /\.kiro\/steering/.test(init);
-    const dp = read(projectRoot, 'src/cli/designerpunk.ts');
-    const dpGov = /path\.join\(\s*pkgRoot\s*,\s*['"`]governance['"`]\s*\)/.test(dp);
-    const dpNoSteering = !/path\.join\(\s*pkgRoot\s*,\s*['"`]\.kiro\/steering['"`]\s*\)/.test(dp);
-    const ok = initGov && initKeepsSteering && dpGov && dpNoSteering;
-    checks.push({
-      surface: 'src/cli/init.ts + src/cli/designerpunk.ts',
-      remediated: ok,
-      detail: `init governance copyDir=${initGov} & keeps .kiro/steering=${initKeepsSteering}; designerpunk governance=${dpGov} & no steering-spawn=${dpNoSteering}`,
-    });
-  }
+  // A4 and A7: RETIRED 2026-10-01 and removed — see the doc comment above for the
+  // standing checks that discharge each sub-check.
 
   // A5: src/figma/VariantAnalyzer.ts + DesignExtractor.ts construct governance/ paths
   {
@@ -385,26 +434,6 @@ export function assertMustFixCouplings(projectRoot: string): CouplingCheck[] {
     });
   }
 
-  // A7: package.json files[] (ADD governance/, KEEP .kiro/steering/), init template,
-  // FileScanner MANAGED_DIRS (ADD governance, keep .kiro/steering).
-  {
-    const pkg = read(projectRoot, 'package.json');
-    const pkgGov = /"governance\/"/.test(pkg);
-    const pkgSteering = /"\.kiro\/steering\/"/.test(pkg);
-    const tmpl = read(projectRoot, 'src/cli/templates/mcp-config.json.template');
-    const tmplGov = /governance/.test(tmpl) && !/\.kiro\/steering/.test(tmpl);
-    const tmplNoDeadTool = !/get_documentation_map/.test(tmpl);
-    const fs2 = read(projectRoot, 'src/cli/sync/FileScanner.ts');
-    const fsGov = /path:\s*'governance'/.test(fs2);
-    const fsSteering = /path:\s*'\.kiro\/steering'/.test(fs2);
-    const ok = pkgGov && pkgSteering && tmplGov && tmplNoDeadTool && fsGov && fsSteering;
-    checks.push({
-      surface: 'package.json files[] + init template + FileScanner MANAGED_DIRS',
-      remediated: ok,
-      detail: `files[] governance=${pkgGov}/steering=${pkgSteering}; template governance=${tmplGov}/no-dead-tool=${tmplNoDeadTool}; MANAGED_DIRS governance=${fsGov}/steering=${fsSteering}`,
-    });
-  }
-
   return checks;
 }
 
@@ -432,15 +461,7 @@ export function assertIdentityPresence(
   referencedIdentityIds: Set<string>,
 ): IdentityPresenceCheck[] {
   // Map id → on-disk filename in .kiro/steering/ (resolved by scanning).
-  const steeringDir = path.join(projectRoot, '.kiro/steering');
-  const files = fs.existsSync(steeringDir) ? fs.readdirSync(steeringDir) : [];
-  const idToFile = new Map<string, string>();
-  for (const f of files) {
-    if (!f.endsWith('.md')) continue;
-    const content = fs.readFileSync(path.join(steeringDir, f), 'utf-8');
-    const m = content.match(/^id:\s*(.+)$/m);
-    if (m) idToFile.set(m[1].trim(), f);
-  }
+  const idToFile = identityIdToFile(projectRoot);
 
   const allIds = new Set<string>([...LOCKED_IDENTITY_IDS, ...referencedIdentityIds]);
 

package/mcp-server/src/tools/find-docs.ts

@@ -42,6 +42,7 @@ export { FIND_DOCS_DEFAULT_LIMIT } from '../query/QueryEngine';
 
 export const findDocsTool = {
   name: 'find_docs',
+  annotations: { readOnlyHint: true },
   description:
     'Discover docs by concept/keyword (concept mode, ranked), or enumerate the full ' +
     'catalog (list mode, paginated). Supersedes get_documentation_map.',

package/mcp-server/src/tools/get-document-full.ts

@@ -16,6 +16,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const getDocumentFullTool = {
   name: 'get_document_full',
+  annotations: { readOnlyHint: true },
   description: 'Get complete document content with metadata. Use when summaries are insufficient and full content is needed.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/get-document-summary.ts

@@ -17,6 +17,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const getDocumentSummaryTool = {
   name: 'get_document_summary',
+  annotations: { readOnlyHint: true },
   description: 'Get document summary with metadata and outline. Returns ~200 tokens to enable informed decisions about loading full content.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/get-index-health.ts

@@ -15,6 +15,7 @@ import { IndexHealth } from '../models';
  */
 export const getIndexHealthTool = {
   name: 'get_index_health',
+  annotations: { readOnlyHint: true },
   description: 'Get the health status of the document index. Returns status (healthy/degraded/failed), errors, warnings, and metrics including document count, section count, cross-reference count, and index size.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/get-section.ts

@@ -26,6 +26,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const getSectionTool = {
   name: 'get_section',
+  annotations: { readOnlyHint: true },
   description:
     'Get specific document section by heading. Returns section content with parent ' +
     'context, a stable sectionId, and siblingHeadings (adjacent sections under the ' +

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

@@ -16,6 +16,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const listCrossReferencesTool = {
   name: 'list_cross_references',
+  annotations: { readOnlyHint: true },
   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,

package/mcp-server/src/tools/rebuild-index.ts

@@ -15,6 +15,7 @@ import { IndexHealth } from '../models';
  */
 export const rebuildIndexTool = {
   name: 'rebuild_index',
+  annotations: { readOnlyHint: false },
   description: 'Rebuild the documentation index from scratch. Use this when the index is corrupted or out of sync. Returns the new index health status after rebuild.',
   inputSchema: {
     type: 'object' as const,

package/mcp-server/src/tools/validate-metadata.ts

@@ -16,6 +16,7 @@ import { ErrorHandler, MCPError } from '../utils/error-handler';
  */
 export const validateMetadataTool = {
   name: 'validate_metadata',
+  annotations: { readOnlyHint: true },
   description: 'Validate document metadata schema. Checks for required fields (Date, Purpose, Organization, Scope, Layer, Relevant Tasks) and returns specific error messages for each issue.',
   inputSchema: {
     type: 'object' as const,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3fn/core",
-  "version": "14.0.0",
+  "version": "15.0.0",
   "description": "True Native cross-platform design system with mathematical foundations",
   "license": "Apache-2.0",
   "author": "Peter Michaels Allen",
@@ -13,19 +13,31 @@
   "browser": "./dist/browser/designerpunk.esm.js",
   "types": "./dist/browser-entry.d.ts",
   "files": [
-    "src/",
+    "CHANGELOG.md",
     "dist/browser/designerpunk.esm.js",
     "dist/browser/designerpunk.esm.min.js",
     "dist/browser-entry.d.ts",
     "dist/**/*.{js,d.ts,json,css,swift,kt}",
     "!dist/**/__tests__/**",
+    "!dist/ios/**",
+    "!dist/android/**",
+    "!dist/web/**",
+    "dist/consumer-canonical/**",
+    "dist/generator/**",
     "dist/__tests__/fixtures/acknowledged-differences.json",
+    "dist/mcp/tool-manifest.json",
+    "dist/name-contract.json",
     "bin/",
     "src/cli/templates/",
-    ".kiro/steering/",
+    ".kiro/steering/Agent-Directory.md",
+    ".kiro/steering/AI-Collaboration-Principles.md",
+    ".kiro/steering/Civitas-System-Overview.md",
+    ".kiro/steering/core-goals.md",
+    ".kiro/steering/DesignerPunk-Systems-Overview.md",
+    ".kiro/steering/Spec-Feedback-Protocol.md",
+    ".kiro/steering/start-up-tasks.md",
+    ".kiro/steering/Task-Completion-Protocol.md",
     "governance/",
-    ".kiro/agents/",
-    "product-template/",
     "mcp-server/src/",
     "mcp-server/package.json",
     "mcp-server/tsconfig.json",
@@ -38,7 +50,38 @@
     "token-index/",
     "family-registry.yaml",
     "design-language/",
-    "designerpunk.config.ts"
+
+    "src/tokens/**",
+    "src/styles/",
+    "src/assets/fonts/**",
+    "!src/assets/fonts/__tests__/**",
+    "src/components/**/{*.schema.yaml,contracts.yaml,component-meta.yaml}",
+
+    "src/types/PrimitiveToken.ts",
+    "src/types/SemanticToken.ts",
+    "src/build/tokens/ComponentToken.ts",
+    "src/build/tokens/ComponentTokenGenerator.ts",
+    "src/build/tokens/PlatformTokens.ts",
+    "src/build/tokens/TokenIntegrator.ts",
+    "src/build/tokens/TokenSelection.ts",
+    "src/build/tokens/TokenSelector.ts",
+    "src/build/tokens/UnitConverter.ts",
+    "src/build/tokens/defineComponentTokens.ts",
+    "src/build/tokens/index.ts",
+    "src/build/tokens/types.ts",
+    "src/build/types/Platform.ts",
+    "src/registries/PrimitiveTokenRegistry.ts",
+    "src/registries/SemanticTokenRegistry.ts",
+    "src/constants/StrategicFlexibilityTokens.ts",
+
+    "src/components/core/**/platforms/ios/*.swift",
+    "!src/components/core/**/platforms/ios/*Tests.swift",
+    "src/components/core/**/platforms/android/*.kt",
+    "!src/components/core/**/platforms/android/*Test.kt",
+    "src/components/core/**/platforms/android/res/**",
+    "src/components/core/**/platforms/android/.gitkeep",
+    "src/blend/*.ios.swift",
+    "src/blend/*.android.kt"
   ],
   "exports": {
     ".": {
@@ -80,7 +123,6 @@
       "require": "./dist/testing/index.js"
     },
     "./grid.css": "./src/styles/responsive-grid.css",
-    "./fonts/inter.css": "./src/assets/fonts/inter/inter.css",
     "./fonts/rajdhani.css": "./src/assets/fonts/rajdhani/rajdhani.css",
     "./fonts/figtree.css": "./src/assets/fonts/figtree/figtree.css",
     "./fonts/commit-mono.css": "./src/assets/fonts/commit-mono/commit-mono.css",
@@ -97,11 +139,16 @@
     "generate:platform-tokens": "tsx scripts/generate-platform-tokens.ts",
     "extract:meta": "tsx scripts/extract-component-meta.ts",
     "prebuild": "npm run generate:types && npm run generate:platform-tokens",
-    "build": "tsc --skipLibCheck && npm run build:validate && npm run build:browser && npm run build:mcp",
+    "build": "tsc --skipLibCheck && npm run build:validate && npm run build:browser && npm run build:name-contract && npm run build:mcp && npm run build:generator",
     "typecheck:scripts": "tsc -p tsconfig.scripts.json",
+    "typecheck": "tsc --noEmit",
     "build:browser": "node scripts/build-browser-bundles.js",
-    "build:mcp": "npm run build:mcp-shared && npx esbuild application-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/application-mcp.js && npx esbuild mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/docs-mcp.js && npx esbuild product-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/product-mcp.js",
-    "build:mcp-shared": "npx esbuild src/cli/shared/resolvePackageRoot.ts src/cli/shared/mcpDataRoots.ts --outdir=dist/cli/shared --platform=node --format=cjs --sourcemap",
+    "build:mcp": "npm run build:mcp-shared && npx esbuild application-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/application-mcp.js && npx esbuild mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/docs-mcp.js && npx esbuild product-mcp-server/src/index.ts --bundle --platform=node --format=cjs --outfile=dist/mcp/product-mcp.js && npm run build:tool-manifest",
+    "build:mcp-shared": "npx esbuild src/cli/shared/resolvePackageRoot.ts src/cli/shared/mcpDataRoots.ts src/cli/shared/bornRepo.ts src/cli/shared/errorCatalog.ts --outdir=dist/cli/shared --platform=node --format=cjs --sourcemap",
+    "build:tool-manifest": "npx tsx scripts/build-tool-manifest.ts",
+    "build:name-contract": "npx tsx scripts/build-name-contract.ts",
+    "build:consumer-canonical": "tsx tools/agent-generator/consumer-entry.ts prepack",
+    "build:generator": "npm run build:consumer-canonical && npx esbuild tools/agent-generator/consumer-entry.ts --bundle --platform=node --format=cjs --define:require.main=undefined --drop-labels=STEWARD_CLI --log-level=warning --outfile=dist/generator/consumer-entry.js",
     "build:watch": "tsc --watch --skipLibCheck",
     "build:verify": "node verify-build.js",
     "build:validate": "npx tsx src/validators/buildValidation.ts",
@@ -109,22 +156,22 @@
     "test": "jest --config jest.functional.config.js",
     "test:all": "jest",
     "test:agent-generator": "jest --config tools/agent-generator/jest.config.js",
+    "test:scripts": "jest --config scripts/jest.config.js",
     "test:consumer": "jest --roots='<rootDir>/tests' --testMatch='**/consumer-integration.test.ts' --runInBand --testTimeout=120000 --forceExit",
+    "test:guard:dynamic-import": "jest --testPathPatterns='DynamicImportGuard' --no-coverage --runInBand",
+    "test:smoke:mcp-boot": "jest --roots='<rootDir>/tests' --testMatch='**/mcp-boot-smoke.test.ts' --no-coverage --runInBand --testTimeout=60000",
+    "test:smoke:browser-boot": "jest --roots='<rootDir>/tests' --testMatch='**/browser-boot-smoke.test.ts' --no-coverage --runInBand --testTimeout=60000",
+    "test:smoke:tool-boot": "jest --roots='<rootDir>/tests' --testMatch='**/tool-boot-smoke.test.ts' --no-coverage --runInBand --testTimeout=60000",
     "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: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",
-    "validate:release-setup": "node scripts/validate-release-setup.js",
-    "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'",
+    "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 skeleton differs from the live theme file (or the generator failed). READ THE DIFF FIRST: this comparison is comment-sensitive, so hand-written rationale comments in the theme file always show as differences. Regenerating (npm run generate:theme-skeleton) preserves override VALUES but DELETES those comments — only do it for real token additions/removals, and restore the rationale afterward.' && exit 1)",
     "generate:theme-skeleton": "npx tsx src/tools/ThemeFileGenerator.ts",
     "serve": "python3 -m http.server 8001",
     "server": "python3 -m http.server 8001",
@@ -133,6 +180,19 @@
     "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",
+    "check:completion-criteria-parity": "tsx scripts/check-completion-criteria-parity.ts",
+    "check:122:noop-probe": "tsx tools/agent-generator/sweeps/noop-probe.ts",
+    "check:122:diff-guard": "tsx tools/agent-generator/diff-guard.ts",
+    "check:122:canonical-vs-truth": "tsx tools/agent-generator/canonical-vs-truth.ts",
+    "check:122:sweep-1-refs": "tsx tools/agent-generator/sweeps/sweep-1-refs.ts",
+    "check:122:sweep-2-skills": "tsx tools/agent-generator/sweeps/sweep-2-skills.ts",
+    "check:122:sweep-3-dupes": "tsx tools/agent-generator/sweeps/sweep-3-dupes.ts",
+    "check:122:sweep-4-ambient": "tsx tools/agent-generator/sweeps/sweep-4-ambient.ts",
+    "check:122:sweep-5-corrected-state": "tsx tools/agent-generator/sweeps/sweep-5-corrected.ts",
+    "check:122:sweep-6-declarations": "tsx tools/agent-generator/sweeps/sweep-6-declarations.ts",
+    "check:122:sweep-7-dispositions": "tsx tools/agent-generator/sweeps/sweep-7-dispositions.ts",
+    "check:122:sweep-8-demotion": "tsx tools/agent-generator/sweeps/sweep-8-demotion.ts",
     "prepack": "npm run build",
     "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",

package/src/build/tokens/defineComponentTokens.ts

@@ -65,6 +65,16 @@ export interface PrimitiveTokenReference {
   name: string;
   /** Unitless base value from the primitive token */
   baseValue: number;
+  /**
+   * Primitive token family (the `category` field of a `PrimitiveToken`, e.g. 'spacing',
+   * 'sizing', 'radius'). OPTIONAL for backward compatibility: minimal `{ name, baseValue }`
+   * reference literals remain valid.
+   *
+   * When present, it is cross-checked against the call's declared `family` by the
+   * family-mismatch guard in {@link defineComponentTokens}. Real primitives from
+   * src/tokens/** always carry it, so the guard is active for all production authoring.
+   */
+  category?: string;
 }
 
 /**
@@ -216,8 +226,40 @@ export function defineComponentTokens<T extends Record<string, TokenDefinition>>
     if (isTokenWithReference(definition)) {
       // Token with primitive reference
       const primitiveToken = definition.reference;
+
+      // FAMILY-MISMATCH GUARD.
+      // The call's `family` is stamped onto every token it registers, and the generator
+      // derives platform output from it — notably the primitive class name used for
+      // reference-path tokens (getFamilyClassName) and the Android `.dp` suffix. A call
+      // that declares one family but references another family's primitive therefore emits
+      // a member that does not exist on the target platform. That is exactly the Button-Icon
+      // defect: a `family: 'spacing'` call referencing `sizingTokens.size600` generated
+      // `SpacingTokens.size600`, a non-existent member (PR #126).
+      //
+      // Only enforced when the reference carries a `category` — minimal `{ name, baseValue }`
+      // literals (used widely in tests) are intentionally exempt rather than rejected.
+      //
+      // Escape hatch: a token that legitimately needs another family's VALUE should use the
+      // value path (`value:`), which asserts no cross-family token-chain claim.
+      if (
+        typeof primitiveToken.category === 'string' &&
+        primitiveToken.category !== family
+      ) {
+        throw new Error(
+          `Token family mismatch in defineComponentTokens() for component '${component}': ` +
+          `token '${key}' is declared in a '${family}' family call but references primitive ` +
+          `'${primitiveToken.name}' from the '${primitiveToken.category}' family. ` +
+          `Every token in a call is stamped with that call's family, which drives platform ` +
+          `output (e.g. the generated '${family.charAt(0).toUpperCase() + family.slice(1)}Tokens' ` +
+          `class reference), so this would emit a non-existent platform member. ` +
+          `Fix: move '${key}' into a separate defineComponentTokens() call with ` +
+          `family: '${primitiveToken.category}', or use the value path if no token-chain ` +
+          `relationship is intended.`
+        );
+      }
+
       const value = primitiveToken.baseValue;
-      
+
       values[key] = value;
       registeredTokens.push({
         name: tokenName,

package/src/cli/templates/mcp-config.json.template

@@ -8,16 +8,7 @@
       "env": {
         "MCP_STEERING_DIR": "./node_modules/@3fn/core/governance"
       },
-      "disabled": false,
-      "autoApprove": [
-        "get_document_summary",
-        "get_document_full",
-        "get_section",
-        "list_cross_references",
-        "validate_metadata",
-        "get_index_health",
-        "rebuild_index"
-      ]
+      "disabled": false
     },
     "designerpunk-application": {
       "command": "node",
@@ -25,22 +16,26 @@
         "./node_modules/@3fn/core/dist/mcp/application-mcp.js"
       ],
       "env": {
-        "COMPONENTS_DIR": "./src/components/core",
+        "COMPONENTS_DIR": "./src/components",
         "PATTERNS_DIR": "./node_modules/@3fn/core/experience-patterns",
         "TEMPLATES_DIR": "./node_modules/@3fn/core/layout-templates",
         "GUIDANCE_DIR": "./node_modules/@3fn/core/family-guidance",
         "REGISTRY_PATH": "./node_modules/@3fn/core/family-registry.yaml",
         "TOKEN_INDEX_DIR": "./token-index"
       },
-      "disabled": false,
-      "autoApprove": [
-        "get_component_catalog",
-        "get_component_summary",
-        "get_component_full",
-        "find_components",
-        "validate_component",
-        "get_component_health"
-      ]
+      "disabled": false
+    },
+    "designerpunk-product": {
+      "command": "node",
+      "args": [
+        "./node_modules/@3fn/core/dist/mcp/product-mcp.js"
+      ],
+      "env": {
+        "PRODUCT_DIR": "./product",
+        "COMPONENT_DIR": "./src/components",
+        "TOKEN_INDEX_DIR": "./token-index"
+      },
+      "disabled": false
     }
   }
 }

package/src/components/core/Avatar-Base/platforms/android/AvatarPreview.kt

@@ -36,11 +36,15 @@ import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.tooling.preview.Preview
 import androidx.compose.ui.unit.dp
 
+// Import DesignTokens for semantic color token references (matches Avatar.android.kt's
+// consumption pattern for non-theme-varying tokens — see Rosetta System Architecture §
+// "Module-Resolution Contract").
+import com.designerpunk.tokens.DesignTokens
+
 // MARK: - Main Preview
 
 /**
@@ -316,7 +320,10 @@ private fun ImageExamplesSection() {
                     Text(
                         text = "src ignored",
                         style = MaterialTheme.typography.labelSmall,
-                        color = Color(0xFFFF9800) /* orange400 - warning color */
+                        // color.feedback.warning.text (→ orange400; no dark-mode override,
+                        // see src/tokens/themes/dark/SemanticOverrides.ts) — was a hardcoded
+                        // hex literal duplicating this token's value (2026-09-13 audit finding).
+                        color = DesignTokens.color_feedback_warning_text
                     )
                 }
                 

package/src/components/core/Container-Base/Container-Base.schema.yaml

@@ -197,9 +197,9 @@ properties:
     description: |
       Border width for the container. Maps to border tokens.
       - none: No border
-      - default: 1px (border.border.default)
-      - emphasis: 2px (border.border.emphasis)
-      - heavy: 4px (border.border.heavy)
+      - default: 1px (border.default)
+      - emphasis: 2px (border.emphasis)
+      - heavy: 4px (border.heavy)
       Border color uses borderColor prop or defaults to color.border.default.
   
   borderColor:
@@ -309,12 +309,10 @@ tokens:
     - space.inset.300
     - space.inset.400
   color:
-    - color.background
-    - color.surface
-    - color.border.default
+    - color.structure.surface
+    - color.structure.border
     - color.structure.border.subtle
-    - color.border.emphasis
-    - color.canvas
+    - color.structure.canvas
   shadow:
     - shadow.container
     - shadow.navigation
@@ -323,9 +321,9 @@ tokens:
     - shadow.toast
     - shadow.tooltip
   border:
-    - border.border.default
-    - border.border.emphasis
-    - border.border.heavy
+    - border.default
+    - border.emphasis
+    - border.heavy
   radius:
     - radius-050
     - radius-100

package/src/components/core/Container-Base/platforms/android/ContainerBase.android.kt

@@ -23,7 +23,7 @@
  * - Hover state support via blend utilities (desktop/ChromeOS with pointer)
  * 
  * @see ../../../types.ts for ContainerBaseProps interface
- * @see ../../../tokens.ts for token reference mappings
+ * @see ../../../Container-Base.refs.ts for token reference mappings
  * @see .kiro/specs/010-container-component/design.md for complete design documentation
  * @see .kiro/specs/034-component-architecture-system for Stemma System details
  * @see .kiro/specs/031-blend-infrastructure-implementation for blend utilities
@@ -569,12 +569,12 @@ fun resolveContainerBaseBorderColor(borderColor: String?, theme: DesignerPunkThe
 }
 
 fun mapContainerBaseBorderToWidth(border: ContainerBaseBorderValue): Dp {
-    // Token references: border.border.default, border.border.emphasis, border.border.heavy
+    // Token references: border.default, border.emphasis, border.heavy
     return when (border) {
         ContainerBaseBorderValue.None -> 0.dp
-        ContainerBaseBorderValue.Default -> borderDefault /* border.border.default */
-        ContainerBaseBorderValue.Emphasis -> borderEmphasis /* border.border.emphasis */
-        ContainerBaseBorderValue.Heavy -> borderHeavy /* border.border.heavy */
+        ContainerBaseBorderValue.Default -> borderDefault /* border.default */
+        ContainerBaseBorderValue.Emphasis -> borderEmphasis /* border.emphasis */
+        ContainerBaseBorderValue.Heavy -> borderHeavy /* border.heavy */
     }
 }