@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/package.json

@@ -1,6 +1,308 @@
 {
   "name": "@ebrindley/build",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.42.1-rc28",
+  "description": "AI orchestration CLI that runs competing provider variants in parallel and synthesizes the best solution",
+  "type": "module",
+  "bin": {
+    "build": "dist/entry.js"
+  },
+  "scripts": {
+    "pretest:native": "tsx scripts/pretest-version-check.ts",
+    "pretest": "npm run -s pretest:native",
+    "pretest:all": "npm run -s pretest:native",
+    "pretest:unit": "npm run -s pretest:native",
+    "pretest:integration": "npm run -s pretest:native",
+    "pretest:integration:hosted": "npm run -s pretest:native",
+    "pretest:workflow-contracts": "npm run -s pretest:native",
+    "pretest:regression": "npm run -s pretest:native",
+    "pretest:core": "npm run -s pretest:native",
+    "pretest:config": "npm run -s pretest:native",
+    "pretest:smoke": "npm run -s pretest:native",
+    "pretest:judge": "npm run -s pretest:native",
+    "pretest:installer": "npm run -s pretest:native",
+    "pretest:providers": "npm run -s pretest:native",
+    "pretest:providers:shared": "npm run -s pretest:native",
+    "pretest:provider:claude": "npm run -s pretest:native",
+    "pretest:provider:copilot": "npm run -s pretest:native",
+    "pretest:provider:cursor": "npm run -s pretest:native",
+    "pretest:provider:codex": "npm run -s pretest:native",
+    "pretest:provider:gemini": "npm run -s pretest:native",
+    "pretest:provider:opencode": "npm run -s pretest:native",
+    "pretest:orchestrator": "npm run -s pretest:native",
+    "pretest:prompts": "npm run -s pretest:native",
+    "pretest:telemetry": "npm run -s pretest:native",
+    "pretest:reliability": "npm run -s pretest:native",
+    "pretest:automation": "npm run -s pretest:native",
+    "pretest:quality": "npm run -s pretest:native",
+    "pretest:cli": "npm run -s pretest:native",
+    "pretest:cli:unit": "npm run -s pretest:native",
+    "pretest:execution": "npm run -s pretest:native",
+    "pretest:scripts": "npm run -s pretest:native",
+    "pretest:coverage": "npm run -s pretest:native",
+    "pretest:coverage:partial": "npm run -s pretest:native",
+    "pretest:coverage:all": "npm run -s pretest:native",
+    "pretest:stress": "npm run -s pretest:native",
+    "pretest:planning": "npm run -s pretest:native",
+    "pretest:planning:unit": "npm run -s pretest:native",
+    "pretest:core:testing": "npm run -s pretest:native",
+    "preplanning:validate": "npm run -s pretest:native",
+    "pretest:e2e": "npm run -s pretest:native && npm run -s build",
+    "pretest:extended": "npm run -s pretest:native",
+    "pretest:changed": "npm run -s pretest:native",
+    "pretest:changed:gate": "npm run -s pretest:native",
+    "pretest:changed:inventory": "npm run -s pretest:native",
+    "pretest:neutrality:sentinel": "npm run -s pretest:native",
+    "preci:stress": "npm run -s pretest:native",
+    "check:config-reads": "tsx scripts/check-config-direct-reads.ts",
+    "check:architecture-boundaries": "tsx scripts/check-architecture-boundaries.ts",
+    "check:public-content": "tsx scripts/check-public-content.ts",
+    "check:no-decorative-glyphs": "tsx scripts/check-no-decorative-glyphs.ts",
+    "check:neutrality": "tsx scripts/check-neutrality.ts",
+    "check:git-exec": "tsx scripts/check-git-exec.ts",
+    "check:hotspot-growth": "node scripts/check-hotspot-growth.mjs",
+    "check:recursive-rm": "tsx scripts/check-recursive-rm.ts",
+    "check:no-outcome-promotion": "tsx scripts/check-no-outcome-promotion.ts",
+    "check:pr-hygiene": "node scripts/check-pr-hygiene.mjs",
+    "check:tracked-paths": "node scripts/check-tracked-paths.mjs",
+    "check:provider-quirks:blocking": "tsx scripts/check-provider-quirks.ts",
+    "check:telemetry-integrity": "tsx scripts/check-telemetry-integrity.ts",
+    "check:processes": "node dist/entry.js processes --health --json",
+    "check:generated": "node scripts/check-generated.mjs",
+    "prebuild": "node scripts/generate-provider-json.js && tsx scripts/generate-judge-scoring-schema.ts && tsx scripts/generate-config-schema.ts",
+    "build": "tsup --config tsup.config.ts",
+    "postbuild": "node scripts/copy-build-assets.mjs",
+    "rebuild": "./scripts/compile-dist.sh",
+    "add-provider": "tsx scripts/add-provider.ts",
+    "providers:generate": "node --import tsx ./src/cli/commands/providers-registry.ts generate",
+    "providers:validate": "node --import tsx ./src/cli/commands/providers-registry.ts validate",
+    "generate:config-schema": "node --import tsx ./scripts/generate-config-schema.ts",
+    "templates:verify": "node ./scripts/verify-templates.mjs",
+    "dev": "tsx watch src/cli/entry.ts",
+    "dev:once": "node --import tsx src/cli/entry.ts",
+    "cli": "node --import tsx src/cli/entry.ts",
+    "test": "bash scripts/test-guard.sh npm run test:unit",
+    "test:all": "BUILD_PREFLIGHT_DONE=1 npm run test:unit && BUILD_PREFLIGHT_DONE=1 npm run test:integration && BUILD_PREFLIGHT_DONE=1 npm run test:regression",
+    "test:unit": "node scripts/test-unit-inventory.mjs",
+    "test:integration": "node scripts/dynamic-node-options.mjs vitest run tests/integration",
+    "test:integration:hosted": "node scripts/run-hosted-integration.mjs",
+    "test:workflow-contracts": "node scripts/dynamic-node-options.mjs vitest run tests/unit/scripts/automation-workflows-yaml.test.ts tests/unit/scripts/release-gate-contract.test.ts",
+    "test:regression": "node scripts/dynamic-node-options.mjs vitest run tests/regression",
+    "test:core": "BUILD_PREFLIGHT_DONE=1 npm run test:telemetry && BUILD_PREFLIGHT_DONE=1 npm run test:automation && BUILD_PREFLIGHT_DONE=1 npm run test:quality && BUILD_PREFLIGHT_DONE=1 npm run test:planning:unit && BUILD_PREFLIGHT_DONE=1 npm run test:core:testing",
+    "test:config": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/config",
+    "test:installer": "bash tests/installer/run-all.sh",
+    "compete-streak": "tsx scripts/compete-streak/run.ts",
+    "release:pack-smoke": "bash scripts/release/pack-and-smoke.sh",
+    "release:bootstrap-pack-smoke": "bash scripts/release/bootstrap-pack-smoke.sh",
+    "release:provider-canary": "npm run -s pretest:native && npm run -s build && BUILD_PROVIDER_CANARY_TESTED_SHA=\"$(git rev-parse HEAD)\" bash scripts/release/provider-canary.sh",
+    "release:local-dist-canary": "node scripts/release/local-dist-canary.mjs",
+    "release:artifacts": "bash scripts/release/prepare-artifacts.sh",
+    "release:dependency-report": "node scripts/release/sbom-license-report.mjs --out-dir .build-project/tmp/release",
+    "release:secret-scan": "bash scripts/release/secret-scan.sh",
+    "release:pre-flip-scan": "bash scripts/release/pre-flip-scan.sh",
+    "release:secret-scan:artifact": "bash scripts/release/secret-scan.sh --artifact",
+    "release:gate": "bash scripts/release/run-gate.sh --mode merge",
+    "verify:release-gate": "npm run release:gate",
+    "release:gate:publish": "bash scripts/release/run-gate.sh --mode publish",
+    "release:verify-all": "npm run -s release:gate && npm run -s test:all && npm run -s release:gate:publish && echo '[release:verify-all] CI-only: shrinkwrap generation (release.yml) mutates working tree; BUILD_EXPECT_SHRINKWRAP=1 runs in CI only' && echo '[release:verify-all] Manual extended suites are opt-in: BUILD_RUN_EXTENDED_TESTS=1 npm run -s test:extended'",
+    "test:smoke": "node scripts/smoke-tests/run.mjs",
+    "smoke-test": "npm run -s test:smoke",
+    "test:providers": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers",
+    "test:providers:shared": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/shared",
+    "test:provider:claude": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/claude",
+    "test:provider:copilot": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/copilot",
+    "test:provider:cursor": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/cursor",
+    "test:provider:codex": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/codex",
+    "test:provider:gemini": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/gemini",
+    "test:provider:opencode": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/providers/opencode",
+    "test:orchestrator": "node scripts/dynamic-node-options.mjs vitest run tests/unit/orchestrator",
+    "test:judge": "node scripts/dynamic-node-options.mjs vitest run tests/unit/orchestrator/judge-verdict-shipping-invariants.test.ts tests/unit/orchestrator/judge-fallback-selector.test.ts tests/unit/orchestrator/matrix-authority.test.ts tests/unit/orchestrator/judge-coordinator.test.ts tests/unit/orchestrator/winner-verification.test.ts tests/unit/core/verification/known-pre-existing-failures.test.ts tests/unit/core/judge/llm-winner-authority.test.ts tests/unit/core/judge/no-post-llm-mutation.test.ts tests/unit/core/judge/winner-from-scores.test.ts tests/unit/core/judge/ai-judge-schema-retry.test.ts",
+    "test:telemetry": "node scripts/dynamic-node-options.mjs vitest run tests/unit/telemetry src/telemetry/__tests__ src/telemetry/variants/__tests__",
+    "test:reliability": "node scripts/dynamic-node-options.mjs vitest run tests/unit/cli/commands/telemetry-reliability.test.ts && node scripts/dynamic-node-options.mjs vitest run src/orchestrator/__tests__/basic-competition-master.test.ts -t \"provider chaos canary\" && node scripts/dynamic-node-options.mjs vitest run src/orchestrator/__tests__/basic-competition-master.test.ts -t \"complex multi-file synthesis fallback\"",
+    "test:automation:preflight": "node scripts/dynamic-node-options.mjs vitest run --silent=passed-only tests/unit/automation/flywheel-preflight.test.ts",
+    "test:automation": "node scripts/dynamic-node-options.mjs vitest run --maxWorkers=1 --no-file-parallelism --silent=passed-only tests/unit/automation --exclude tests/unit/automation/flywheel-preflight.test.ts && npm run -s test:automation:preflight",
+    "test:quality": "node scripts/dynamic-node-options.mjs vitest run tests/unit/quality",
+    "test:planning:unit": "node scripts/dynamic-node-options.mjs vitest run --maxWorkers=1 --no-file-parallelism tests/unit/planning src/planning/__tests__",
+    "test:core:testing": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/memory tests/unit/core/testing",
+    "test:prompts": "node scripts/dynamic-node-options.mjs vitest run tests/unit/prompts tests/unit/types tests/unit/utils tests/unit/core/judge/ai-judge-prompt-3bucket-excerpt.test.ts tests/unit/core/judge/criteria-ledger-confidence.test.ts tests/unit/core/judge/winner-from-scores.test.ts tests/unit/core/judge/evidence-proportionality-gate.test.ts tests/unit/core/judge/signal-reliability.test.ts src/prompts src/core/judge/__tests__",
+    "test:cli": "node scripts/dynamic-node-options.mjs vitest run tests/integration/providers-registry-cli.test.ts",
+    "test:cli:unit": "node scripts/dynamic-node-options.mjs vitest run tests/unit/cli",
+    "test:execution": "node scripts/dynamic-node-options.mjs vitest run tests/unit/core/execution",
+    "test:scripts": "node scripts/dynamic-node-options.mjs vitest run tests/unit/scripts",
+    "test:watch": "vitest watch",
+    "test:coverage": "node scripts/dynamic-node-options.mjs vitest run tests/unit/telemetry tests/unit/core tests/unit/orchestrator tests/unit/automation tests/unit/quality tests/unit/types tests/unit/utils --coverage",
+    "test:coverage:partial": "node scripts/dynamic-node-options.mjs vitest --config vitest.partial.config.ts run --coverage",
+    "test:coverage:all": "node scripts/dynamic-node-options.mjs vitest run --config vitest.partial.config.ts tests/unit/telemetry tests/unit/automation tests/unit/quality tests/unit/planning tests/unit/core/memory/memory-store.test.ts tests/unit/core/providers tests/unit/orchestrator tests/unit/prompts tests/unit/types tests/unit/utils tests/unit/cli tests/unit/core/judge/ai-judge-prompt-3bucket-excerpt.test.ts tests/unit/core/judge/criteria-ledger-confidence.test.ts tests/unit/core/judge/winner-from-scores.test.ts src/prompts src/core/judge/__tests__ tests/integration/providers-registry-cli.test.ts tests/integration/validate-providers-script.test.ts tests/unit/scripts --coverage.enabled",
+    "test:stress": "node scripts/dynamic-node-options.mjs node --import tsx tests/stress/memory-stress.js",
+    "ci:stress": "NODE_ENV=ci node scripts/dynamic-node-options.mjs node --import tsx tests/stress/memory-stress.js --ci",
+    "check:package-docs": "node --import tsx scripts/check-package-docs.mjs",
+    "preflight:native": "node ./scripts/preflight-native.mjs",
+    "verify:dist": "tsx scripts/verify-dist.ts",
+    "verify:release": "npm run -s verify:dist && node --import tsx ./scripts/verify-release-readiness.ts",
+    "prepublishOnly": "npm run -s verify:dist",
+    "audit:errors": "node --import tsx ./scripts/audit-error-handling.ts --skip-destructive",
+    "audit:post-llm-mutations": "node --import tsx ./scripts/audit-post-llm-mutations.ts --strict",
+    "clean": "rm -rf dist",
+    "typecheck": "npm run -s typecheck:source && npm run -s typecheck:tooling && npm run -s typecheck:bb-plugin && npm run -s check:test-imports",
+    "typecheck:source": "tsc --noEmit -p tsconfig.typecheck-full.json",
+    "typecheck:tooling": "tsc --noEmit -p tsconfig.tooling.json",
+    "typecheck:bb-plugin": "tsc --noEmit -p integrations/bb-plugin-build/tsconfig.json",
+    "check:test-imports": "tsx scripts/check-test-imports.ts",
+    "typecheck:providers:opencode": "tsc --noEmit -p tsconfig.providers-opencode.json",
+    "lint": "biome check --changed --no-errors-on-unmatched",
+    "lint:ci": "node scripts/lint-ci.mjs",
+    "lint:full": "biome check src/ tests/ scripts/",
+    "lint:fix": "biome check --write --changed --no-errors-on-unmatched",
+    "instructions:lint": "node --import tsx ./scripts/instruction-lint.ts",
+    "instructions:surface": "node --import tsx ./scripts/instruction-surface.ts",
+    "format": "biome format --write src/ tests/ scripts/",
+    "format:check": "biome format src/ tests/ scripts/",
+    "check:esm": "node scripts/check-esm-compliance.js",
+    "prepare": "node scripts/setup-git-hooks.mjs",
+    "prepare:full": "npm run clean && npm run templates:verify && npm run providers:validate && npm run providers:generate && npm run build && npm run check:esm && npm run -s verify:dist",
+    "prepack": "npm run -s check:package-docs && if [ \"${BUILD_SKIP_PREPACK:-0}\" = \"1\" ]; then echo \"[prepack] BUILD_SKIP_PREPACK=1; skipping prepare:full\"; else npm run prepare:full; fi",
+    "canary:backlog-execute": "node --import tsx ./scripts/reliability/run-backlog-execute-canary.ts",
+    "canary:backlog-execute:validate": "node --import tsx ./scripts/reliability/validate-backlog-execute-canary-artifacts.ts",
+    "canary:backlog-execute:scorecard": "node --import tsx ./scripts/reliability/reliability-scorecard.ts",
+    "test:planning": "node scripts/dynamic-node-options.mjs vitest run tests/planning",
+    "test:planning:watch": "vitest watch tests/planning",
+    "planning:validate": "node scripts/dynamic-node-options.mjs vitest run tests/planning/validation.test.ts",
+    "backup:telemetry": "node --import tsx scripts/backup-telemetry-db.ts",
+    "restore:telemetry": "node --import tsx scripts/restore-telemetry-db.ts",
+    "test:e2e": "BUILD_E2E_USE_DIST=1 node scripts/dynamic-node-options.mjs vitest run tests/e2e --maxWorkers=1 --no-file-parallelism --reporter=verbose",
+    "test:extended": "if [ \"${BUILD_RUN_EXTENDED_TESTS:-0}\" = \"1\" ]; then BUILD_PREFLIGHT_DONE=1 npm run -s test:e2e; else echo '[test:extended] SKIP: set BUILD_RUN_EXTENDED_TESTS=1 to run test:e2e'; fi",
+    "test:changed": "node ./scripts/test-changed.mjs",
+    "test:changed:gate": "node ./scripts/test-changed-gate.mjs",
+    "test:changed:inventory": "node ./scripts/test-changed-inventory.mjs",
+    "test:neutrality:sentinel": "node --import tsx ./scripts/run-non-node-verification-sentinel.ts",
+    "test:fast": "npm run test:changed",
+    "test:staged": "npm run test:changed -- --staged",
+    "test:related": "node scripts/dynamic-node-options.mjs vitest related",
+    "test:watch:orchestrator": "node scripts/dynamic-node-options.mjs vitest watch tests/unit/orchestrator",
+    "test:watch:prompts": "node scripts/dynamic-node-options.mjs vitest watch tests/unit/prompts tests/unit/types tests/unit/utils tests/unit/cli tests/unit/core/judge/ai-judge-prompt-3bucket-excerpt.test.ts tests/unit/core/judge/criteria-ledger-confidence.test.ts tests/unit/core/judge/winner-from-scores.test.ts src/prompts src/core/judge/__tests__",
+    "ci:gate": "npm run release:gate",
+    "resources": "node scripts/show-resource-tier.mjs",
+    "ci:nightly": "npm run -s check:no-decorative-glyphs && npm run -s check:public-content -- --advisory --tier-b && npm run -s test:unit && npm run -s test:integration && npm run -s test:regression && npm run -s test:e2e"
+  },
+  "keywords": [
+    "ai",
+    "orchestration",
+    "cli",
+    "development",
+    "automation",
+    "variant-competition",
+    "quality-gates",
+    "telemetry",
+    "claude",
+    "codex",
+    "cursor",
+    "multi-provider"
+  ],
+  "author": "Ed Brindley <61567470+ebrindley@users.noreply.github.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ebrindley/build#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ebrindley/build.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ebrindley/build/issues"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "files": [
+    "dist/",
+    "!dist/**/*.map",
+    "!dist/.build-meta.json",
+    ".nvmrc",
+    "schemas/",
+    "scripts/sync.sh",
+    "scripts/assert-node-runtime.mjs",
+    "scripts/preflight-native.mjs",
+    "scripts/setup-git-hooks.mjs",
+    "scripts/write-node-launcher.sh",
+    "src/resources/",
+    "templates/",
+    "integrations/bb-plugin-build/package.json",
+    "integrations/bb-plugin-build/server.ts",
+    "integrations/bb-plugin-build/app.tsx",
+    "integrations/bb-plugin-build/app.css",
+    "integrations/bb-plugin-build/src/",
+    "integrations/bb-plugin-build/README.md",
+    ".build-project/providers/",
+    "!.build-project/providers/*.lock",
+    "!.build-project/README.md",
+    "!docs/reference/README.md",
+    "README.md",
+    "INSTALL.md",
+    "THIRD_PARTY_NOTICES.txt",
+    "docs/README.md",
+    "docs/getting-started/README.md",
+    "docs/getting-started/QUICK_START.md",
+    "docs/getting-started/SETUP.md",
+    "docs/CLI_REFERENCE.md",
+    "docs/PROVIDER_SETUP.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/reference/AGENT_CONTEXT.md",
+    "docs/reference/DELIVERY_ONBOARDING.md",
+    "docs/reference/PROVIDER_RELEASE_TIERS.md",
+    "docs/reference/SECURITY.md",
+    "docs/reference/TELEMETRY_PRIVACY.md",
+    ".github/SECURITY.md",
+    "npm-shrinkwrap.json",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "async-lock": "^1.4.1",
+    "better-sqlite3": "^13.0.3",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
+    "decimal.js": "^10.6.0",
+    "execa": "^9.0.0",
+    "js-yaml": "^4.3.1",
+    "jsonc-parser": "^3.3.1",
+    "minimatch": "^11.0.1",
+    "p-limit": "^7.2.0",
+    "proper-lockfile": "^4.1.2",
+    "semver": "^7.7.3",
+    "yaml": "^2.8.3",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.4",
+    "@types/async-lock": "^1.4.2",
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.10.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^19.2.14",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "react": "^19.2.6",
+    "tsup": "^8.5.0",
+    "tsx": "^4.0.0",
+    "typescript": "5.4.5",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=24.0.0 <25.0.0 || >=26.0.0 <27.0.0",
+    "npm": ">=9.0.0"
+  },
+  "overrides": {
+    "esbuild": "0.28.1",
+    "picomatch": "4.0.4"
+  },
+  "optionalDependencies": {
+    "tiktoken": "^1.0.22"
+  }
+}

package/schemas/README.md

@@ -0,0 +1,80 @@
+# JSON Schema Directory
+
+This directory contains JSON Schema definitions for configuration files used throughout Build.
+
+## Purpose
+
+JSON Schemas provide:
+- **Editor validation**: Real-time error checking in VS Code, IntelliJ, etc.
+- **Auto-completion**: Smart suggestions when editing config files
+- **Documentation**: Inline descriptions for each configuration field
+- **Type safety**: Catch configuration errors before runtime
+
+## Available Schemas
+
+### judge-scoring.schema.json
+
+Schema for `src/core/config/judge-scoring.json`.
+
+- **Source of truth**: Zod schema in `src/core/config/judge-scoring.ts`
+- **Generated by**: `scripts/generate-judge-scoring-schema.ts`
+- **Auto-generated on**: `npm run build` (via prebuild hook)
+
+**Usage in judge-scoring.json**:
+```json
+{
+  "$schema": "../../../schemas/judge-scoring.schema.json",
+  "defaults": { ... }
+}
+```
+
+### Other Schemas
+
+- `build.config.schema.json` - Canonical generated project configuration schema
+- `config-v1.schema.json` - Legacy migration schema (explicit use only)
+- `execution-config.schema.json` - Legacy execution migration fragment
+- `provider-config.schema.json` - Legacy provider migration fragment
+- `telemetry-config.schema.json` - Legacy telemetry migration fragment
+- `user-preferences.schema.json` - User preferences
+
+## Maintaining Schemas
+
+### Adding a New Schema
+
+1. **Define Zod schema** in source code (e.g., `src/core/config/my-config.ts`)
+2. **Create generation script** (see `scripts/generate-judge-scoring-schema.ts` as template)
+3. **Add to prebuild hook** in `package.json`
+4. **Add tests** to ensure schema stays in sync
+5. **Reference schema** in your JSON file with `$schema` field
+
+### Keeping Schemas in Sync
+
+The schema generation is **automated**:
+- Runs during `npm run build` via prebuild hook
+- Tests verify schema matches Zod validation
+- CI/CD fails if schema is out of sync
+
+**Manual regeneration**:
+```bash
+tsx scripts/generate-judge-scoring-schema.ts
+```
+
+## Testing
+
+Tests ensure schemas stay in sync with their source of truth:
+
+```bash
+npm run test:config
+```
+
+See `tests/unit/core/config/judge-scoring-schema.test.ts` for example tests.
+
+## Editor Integration
+
+Most editors auto-detect `$schema` references:
+
+**VS Code**: Automatically provides IntelliSense and validation
+**IntelliJ/WebStorm**: Built-in JSON schema support
+**vim/neovim**: Use LSP with jsonls
+
+No additional configuration needed - just add the `$schema` field to your JSON files.