@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/CHANGELOG.md

@@ -0,0 +1,661 @@
+# Changelog
+
+All notable changes to Build will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Removed
+
+- Removed the variant strategy axis (`conservative`, `innovative`, `hybrid`,
+  `fast`, and the `fusion` variant token). Variant specs are now
+  `provider[:model][:effort-level][:mode]`, run diversity comes from provider,
+  model, and reasoning effort, and every variant receives one packaged execution
+  contract. `build explain strategies` is gone; `build explain variants`
+  documents the grammar. Strategy config fields, `BUILD_DEFAULT_STRATEGY`,
+  `BUILD_STRICT_STRATEGIES`, and the flywheel `prefer-strategy` tie-breaker are
+  removed. Fusion the feature is unchanged and runs on `runSemantics: 'fusion'`.
+  See ADR-025.
+- Removed `build provider setup --plugins`. No shipped provider defines a
+  plugin, so every request printed "Plugin not found". Provider configs no
+  longer accept a `plugins` field. Project configs that declare the removed
+  `templated_cli` engine are now rejected by the execution-field trust check
+  instead of a separate templated_cli error.
+
+### Fixed
+
+- A `BUILD_HOME` anywhere under the user's home or a temp root is now accepted by
+  the provider sandbox (only its `state` and `data` subtrees are granted; `config`
+  stays denied) and by the worktree-base safety check on first run, using the same
+  trust rule as config. Symlinks out of the home are still rejected. The installer
+  and `upgrade` source build no longer pass `BUILD_HOME`, `BUILD_CONFIG_DIR` or
+  `BUILD_DATA_DIR` to `npm ci` and `npm pack`.
+- Preserve cleanup-eligible Git worktrees when their status inspection times out
+  or is terminated, instead of treating an absent exit code as a clean checkout.
+
+### Changed
+
+- `build plan backlog finalize` titles its archive pull request
+  `Archive backlog item: <item title>` instead of `chore(backlog): archive <id>`, with a
+  one-line body naming the item and its linked PR instead of a generated-by line, and
+  under the `checkout` backend uses the same subject for the archive commit. Set
+  `git.messageStyle: conventional` for `chore(backlog): archive <item title>`.
+
+- Bounded second waves add untried providers, then higher reasoning effort,
+  instead of untried strategies. `--variants N` now means the first N available
+  providers from the resolved provider order. The default competition field is
+  two providers running the same contract. Strategy timeout multipliers
+  (innovative 1.3x, hybrid 1.1x, fast 0.7x) are removed.
+- New branch, worktree, and state-file names are
+  `feature/{id}-{provider}-{mode}-{suffix}`,
+  `{taskId}-{suffix}-{poolId}`, and `{id}-{provider}-{mode}-{suffix}.json`. The
+  suffix derives from full canonical variant identity.
+- Telemetry stops writing `strategy` and `strategy_state`; the columns stay
+  nullable permanently so history remains readable, and
+  `variant_executions_v2` gains `prompt_contract_ref`.
+- Bare `--model auto` follows the configured provider instead of implying Cursor.
+  Omit `--model` to use Build's configured model, or specify
+  `--engine cursor --model auto` for Cursor Auto. Shared `auto`/`default`
+  selections no longer update saved Cursor model preferences.
+
+### Deprecated
+
+- Variant specs and consumer config carrying a removed strategy token are
+  accepted with a warning for one release, then rejected.
+
+## [v1.42.0-rc6] - 2026-09-02
+
+### Fixed
+
+- Corrected zero-test and missing-tool verification classification across
+  Vitest, Go, Maven, Gradle, and wrapped test runners.
+- Preserved sprint apply verification when managed task files are archived.
+- Excluded Codex runtime-home artifacts from judged delivery while retaining
+  fail-closed protection for security-sensitive paths.
+- Finalized interrupted autoloops before process shutdown and recorded release
+  artifact source provenance.
+
+## [v1.42.0-rc5] - 2026-09-01
+
+### Fixed
+
+- Preserved resolver-detected TypeScript source evidence during initialization,
+  including projects without a TypeScript dependency or `tsconfig`.
+- Clarified deferred reviewer authentication readiness, returned both applicable
+  dirty/protected-branch remediations, and removed duplicated debug labels.
+
+## [v1.42.0-rc4] - 2026-09-01
+
+### Added
+
+- Added canonical provider/model routing, configurable review policies, portable
+  telemetry bundles, task-run receipts, and the Parallax analysis workflow.
+- Added BB planning, task, sprint-execution, result, and activity surfaces.
+
+### Changed
+
+- Promoted judged competition, competition apply, and default agentic synthesis
+  into the dependable supported surface.
+- Consolidated local CLI provider execution and removed retired cloud, direct
+  API, TUI, simulation, PatternBank, coverage, roadmap, and Swarm surfaces.
+
+### Fixed
+
+- Hardened execution, synthesis, judging, verification, cancellation, managed
+  sync, first-run setup, and delivery evidence boundaries.
+- Improved release security scans, provider canary coverage, local CI
+  scheduling, and target-language-neutral changed-test selection.
+
+## [v1.42.0-rc3] - 2026-08-24
+
+### Fixed
+
+- Added the unambiguous `build upgrade --target-version <version>` option and
+  documented the one-time RC1/RC2 equals-form transition.
+- Removed unused release-candidate JSON fields added during RC2 and retained
+  only the clearer human-facing working-tree identity label.
+
+## [v1.42.0-rc2] - 2026-08-24
+
+### Fixed
+
+- Prepared Build-managed launchers before npm reinstall and restored them on
+  failure, preventing global-bin `EEXIST` collisions during installer/upgrade.
+- Distinguished configured auth assumptions from execution-verified provider
+  readiness in setup and installer output.
+- Made Node 24, PATH precedence, headless authentication, and RC install
+  guidance deterministic across first-user documentation.
+
+## [v1.42.0-rc1] - 2026-08-23
+
+### Changed
+
+- Standardized the first-user Node, npm, Claude, provider setup, init, and
+  doctor sequence for interactive and non-interactive environments.
+- Resolved user configuration paths in first-run and provider-default output
+  instead of printing stale XDG paths.
+- Added prerelease publishing through the npm `rc` dist-tag and clarified that
+  strict readiness failures can leave the package installed without a success
+  manifest.
+
+## [v1.42.0] - 2026-08-21
+
+This first npm publication of the 1.42 line includes the accumulated changes
+listed in this section since the `v1.42` source-readiness milestone.
+
+### Added
+
+- Published Build through the public `@ebrindley/build` npm package and the
+  official repository installer, including exact-version install and update
+  verification.
+
+### Changed
+
+- Releases publish to the npm `next` tag first, verify the registry install in
+  a clean prefix, and create a draft GitHub release. Operators promote the
+  verified version to `latest` only after clean-environment dogfood testing.
+
+- Bare `build run "<task>"` now executes the provider from
+  `build config resolved`. It no longer silently swaps providers from domain
+  scoring. Restore the old behavior with `--provider-routing auto`.
+  `--auto` / `--profile auto` still plan execution strategy and may route on
+  that path. `--explain-routing` still analyzes; when routing is not applied it
+  says so. Dry-run and live bare runs now agree on the resolved provider.
+
+- Simplified the public CLI hierarchy for 1.42 readiness: ordinary
+  `build --help` presents exactly eleven Public roots (`init`, `plan`, `ask`,
+  `run`, `build`, `scan`, `provider`, `config`, `doctor`,
+  `telemetry`, `cleanup`) grouped by four domains. Full help
+  (`build --help-full`) groups Public / Advanced / Internal. Canonical nested
+  paths include `plan {capture,next,backlog,sprint,task,debt,parking,roadmap}`,
+  `scan {findings,issues,ingest,suppressions}`, `run {task,sprint,fusion,competition,flywheel,autoloop}`,
+  `init knowledge`, and `config instructions`. Demoted roots remain callable as
+  hidden compatibility aliases through 1.42.x. Authoritative classification is
+  `src/cli/utils/command-tiers.ts`.
+- Ordinary help is now four domains (Overview, Plan, Run, Settings) and eleven
+  public roots. `run` nouns are task, sprint, fusion, and competition.
+  `compete` is a hidden compatibility alias of `run competition`. `build`
+  remains a public root. Enforcement counts: Public roots 12 → 11; Hidden
+  compatibility roots 28 → 29; Ordinary-help domains 5 → 4.
+
+### Removed
+
+- Retired the Build Claude Code plugin product surface. Build is one CLI that
+  invokes provider CLIs directly; Claude remains available through its native
+  CLI provider. The former plugin marketplace install, slash-command pack, hook
+  layer, plugin command aliases, Claude-only no-sync/repo-policy/hint hooks,
+  session-triggered nightly invocation, and automatic plugin post-sync cleanup
+  are removed. Legacy private-beta installs may run
+  `build provider disconnect claude --scope user|project|local` to uninstall a
+  leftover plugin registration; that command does not sign out, revoke
+  credentials, or disable Claude. Project/local cleanup must run from each
+  affected repository.
+- Removed the broken Claude Code settings templates
+  (`.build-project/config/claude-settings.template.json` and its packaged copy
+  `templates/.build-project/config/claude-settings.template.json`). Both shipped an
+  unscoped `git add .` after every Write/Edit that would stage the entire dirty
+  repo and an unguarded `Stop` session logger; the root `.build-project/config` copy
+  additionally logged `$CLAUDE_TOOL_INPUT`, which Claude Code never sets (hook
+  payloads arrive as JSON on stdin), so its command-audit hook logged an empty
+  payload. No code reads or copies these files by name — their only function
+  was inviting users to adopt provably broken, hazardous configuration.
+- Removed the broken, unconsumed Claude Code hook telemetry layer from the
+  former `build` plugin manifest (`plugins/build/hooks/hooks.json`): the
+  `Stop` session-completion logger, the `Write|Edit` audit logger, the two
+  `Bash(build*)` command loggers, and the `Read(*.build-project/reasoning/*.md)`
+  reasoning-gate logger. The Stop logger errored in every Claude Code session
+  whose cwd lacked `.build-project/telemetry/` (relative path, no guard); the
+  Write/Edit and Bash loggers referenced `$CLAUDE_TOOL_INPUT`, which Claude Code
+  never sets (hook payloads arrive as JSON on stdin), so they logged empty or
+  nothing; and no code ever read `claude-code-audit.log` — Build's real
+  telemetry is CLI-written (invocations.db, autoloop-history.jsonl). Also
+  removed the dead opt-in auto-format and auto-stage hooks
+  (`BUILD_CLAUDE_AUTO_FORMAT` / `BUILD_CLAUDE_AUTO_STAGE`), which depended on
+  the same unset variable, were globally scoped (would mutate unrelated repos),
+  and hardcoded Biome + TS/JS in violation of target-neutrality [B6]. The
+  remaining plugin hooks and slash commands are retired with the plugin surface
+  above.
+- Removed the experimental concurrent web capability from `build run`
+  (`--web`, `--web-api-key`, `--web-endpoint`, `--web-timeout`,
+  `--web-rate-limit`, and the `BUILD_EXPERIMENTAL_WEB` /
+  `CONCURRENT_WEB_API_KEY` configuration keys). The integration targeted an
+  external web-capabilities service that never shipped; the surface was
+  opt-in-gated and never dialed its placeholder endpoint, but the dead flags
+  confused release audits and first-time users.
+
+### Changed
+
+- Added opt-in, configurable execution casts with `orchestrator`, `executor`,
+  and independent `reviewer` roles. The shipped `frontier-codex` and
+  `frontier-claude` profiles use a frontier planner at high effort, Grok as the
+  implementation executor with eight native subagents, and the other frontier
+  provider for review. When no provider/model CLI override is supplied, the
+  configured orchestrator now owns initial decomposition; explicit invocation
+  choices still win, and computed planning choices do not override the executor
+  role. The semantic `frontier` mapping selects Claude Fable 5 or GPT-5.6 Sol;
+  generic provider defaults remain unchanged, and Grok follows its configured
+  CLI model unless explicitly overridden. Invalid or unavailable active-profile
+  role bindings now fail closed before generated edit workflows are stamped.
+  Reviewer readiness preflight uses the exact post-failover bindings frozen in
+  each workflow stamp, so it cannot validate a different reviewer than dispatch.
+- Claude's terminal-event completeness rule applies to every analysis consumer,
+  including planning and orchestration: transport completion without a terminal
+  result is never treated as a successful model response.
+
+#### Runtime support
+- Raised Build's required Node.js runtime from 22.x to 24.x across package
+  metadata, installer checks, CLI health/runtime gates, CI setup, release
+  packaging, and documentation.
+
+### Fixed
+
+- Shipped frontier profiles now resolve reviewers at medium reasoning effort
+  while keeping orchestrators at high effort.
+- Grok now follows the installed CLI's configured model by default instead of
+  pinning a version. Set `defaults.providers.grok.model` in project or user
+  configuration to pass an explicit model; `auto` omits `-m`/`--model`. The
+  executor-role resolver now honors those provider-scoped settings ahead of its
+  implicit `fast` role, and `config resolved --role executor --provider <id>`
+  reports model provenance plus provider-native discovery where supported. The
+  rejected legacy `grok-build` id is no longer advertised as an available model.
+- `backlog execute --review-only`/`--dry-run` no longer exits 2 with no output
+  when another execution (or a stale lock) is active: review mode is now fully
+  read-only and skips the execution lock, and the active-execution gate prints
+  its diagnostic before setting the exit code.
+- Context injection for compete/Fusion no longer offers nonexistent files as
+  relevant context: candidates are existence-checked against the target root
+  (prompt-referenced phantom paths and git-deleted files are dropped), and
+  discovery is pinned to the resolved project root instead of the process
+  working directory, so invocations from a parent directory cannot sweep
+  sibling repos into context.
+
+#### Release-readiness: docs golden path and behavior honesty
+- Reconciled the documentation golden path to a single consistent flow. `docs/README.md`
+  and the Grok troubleshooting section previously implied Grok single-variant `compete`
+  was the first-success path; all docs now state that Claude and Codex are the primary
+  validated providers (single-variant `compete --judge off` → `compete apply`), with
+  Grok/Cursor/OpenCode as supported validated alternatives, matching `README.md` and
+  `docs/getting-started/QUICK_START.md`.
+- Clarified the Node prerequisite. The global Build requirement (Node.js 24.x, per
+  `package.json` engines) is stated consistently; per-provider "Prerequisite: Node.js Nx+"
+  lines in `docs/PROVIDER_SETUP.md` now make clear they are each external CLI's own minimum,
+  not Build's.
+- Documented true lifecycle-event behavior. `docs/reference/LIFECYCLE_HOOKS.md` now states
+  that execution events are recorded automatically, while work-item creation and PR/commit
+  tracking events are not yet automatic and must be recorded with `build lifecycle track`.
+- Documented true budget behavior. `BUILD_FLYWHEEL_BUDGET_MODE=hard_cap` is recognized but
+  always treated as advisory (invariant [B5]); it never blocks or cancels execution. This is
+  now stated in `docs/FLYWHEEL.md`.
+
+### Changed
+
+#### `backlog list` defaults to active scope
+- `build backlog list` (and the MCP `backlog-list` tool) now default to the **active** scope —
+  inbox + reviewed items from the live bucket only. Archived items are hidden by default and
+  reported as a tail-note count; use `--status archived` or the new `--include-archived` flag
+  to see them. This fixes archived items (often the majority in mature repos) drowning active
+  work in the default view.
+- **Breaking (JSON):** default `build backlog list --json` no longer includes the ARCHIVED
+  group. New metadata fields are added on every listing: `scope`
+  (`active` | `with-archived` | `status`) and `archivedItems` ({ `count`, `included` });
+  `statusFilter` is retained for back-compat.
+- The MCP `backlog-list` handler's no-status default previously returned live-bucket stragglers
+  (stale `status: archived` files never physically moved) and missed the physical archive
+  directory, diverging from the CLI. Both surfaces now derive their default set from a single
+  shared read-model, so they cannot drift.
+
+#### Testing Infrastructure
+- **Upgraded Vitest from v3.2.4 to v4.0.8** (2025-01-07)
+  - Updated test runner to latest major version
+  - Migrated mock patterns to v4-compatible strategy using `vi.hoisted()`
+  - Updated pool configuration: `poolOptions.forks.singleFork` → `maxWorkers: 1, isolate: false`
+  - Fixed 45 tests in `dashboard.test.ts` for v4 mock behavior changes
+  - Added defensive check in `dashboard.ts` for undefined query results
+  - **Test Success Rate**: 99.5% (401/403 tests passing)
+  - **Breaking Changes**: See `docs/migrations/archive/vitest-v4-migration.md`
+
+### Technical Details
+- **Config Changes**: `vitest.config.ts` updated for v4 pool architecture
+- **Mock Pattern**: Replaced `DatabaseConstructor.mock.results` with `vi.hoisted()` tracking
+- **Known Limitation**: 2 integration tests (`cli.leaderboard.flags.test.ts`, `dashboard.fscore.test.ts`)
+  fail when run with full suite due to `isolate: false` global mock pollution (pass individually)
+
+## [v1.42] - 2026-05-17
+
+> **About the version jump (v0.x → v1.42):** Build's npm package version remains
+> semver-compliant (`1.42.0`); the `v1.42` label aligns human-facing branding across
+> surfaces and marks the open-source readiness milestone. The development work that was
+> tracked below under "v0.2.0 (Unreleased)" was never published as a standalone v0.2.0
+> release — it was folded into this line. See that section for the detailed history.
+
+### Added
+- Open-source readiness release. The repository is MIT-licensed and prepared for public issues, discussions, and pull requests (see CONTRIBUTING.md).
+- `.github/SECURITY.md`, `.github/SUPPORT.md`, and GitHub issue templates.
+
+### Changed
+- Version branding aligned to `v1.42` across human-facing surfaces. The npm package remains semver-compliant at `1.42.0`.
+
+## v0.2.0 development (never released as a standalone version — superseded by v1.42)
+
+**Note**: This work was developed during the Nov 2025 – May 2026 window and folded into
+the `v1.42` line rather than shipping as a separate `v0.2.0` tag; it is retained here for
+history. It introduced new implementations alongside deprecated code to enable gradual
+migration, so code size temporarily increased during the deprecation period. Target
+improvements are realized when the deprecated code is removed (tracked as a future cleanup).
+
+### Added
+
+#### Structured Warning System
+- **Complete structured warning implementation** with 17 warning codes across 5 categories
+  - Registry-based warnings with centralized metadata and recovery mechanisms
+  - Post-execution validation with 3 core rules and false-positive detection
+  - CLI display with 4 verbosity levels (silent, minimal, normal, verbose)
+  - Telemetry integration for trend analysis and dashboard visualization
+  - Test utilities for easy testing with `WarningCollector`
+  - Performance: <0.1ms emission overhead per warning
+
+- **Warning Categories and Codes**:
+  - **Workspace Edits** (WS-xxx): File operation warnings
+    - WS-001: Edit emitted but not applied (INFO)
+    - WS-002: File write failed, retrying (WARN)
+    - WS-003: Edit failed after all retries (ERROR)
+  - **Provider Execution** (PR-xxx): Provider-related issues
+    - PR-001: Execution failed with non-zero exit (ERROR)
+    - PR-002: Execution timed out, using partial results (WARN)
+    - PR-003: API rate limit approaching (INFO)
+  - **Validation** (VAL-xxx): Test/lint/build warnings
+    - VAL-001: Test suite failed (ERROR)
+    - VAL-002: Linting errors detected (WARN)
+    - VAL-003: Build succeeded with warnings (WARN)
+  - **Performance** (PERF-xxx): Resource and timing warnings
+    - PERF-001: Execution exceeded time budget (WARN)
+    - PERF-002: Memory usage approaching threshold (INFO)
+  - **Configuration** (CFG-xxx): Config-related warnings
+    - CFG-001: Missing API key, using fallback (WARN)
+    - CFG-002: Using default configuration value (INFO)
+    - CFG-003: Invalid configuration value (ERROR)
+
+- **User Configuration**:
+  - Suppression rules for noisy warnings (`~/.build/config.json`)
+  - Project-level warning config (`.build-project/warning-config.json`)
+  - Verbosity control via CLI flags (`--warnings verbose|normal|minimal|silent`)
+  - Environment variable support (`BUILD_WARNINGS`, `BUILD_WARNINGS_CONSOLE`)
+  - Output channel selection (cli, telemetry, file)
+
+- **Migration Support**:
+  - Coexists with `console.warn/error` during 6-month deprecation period
+  - Migration guide in `docs/STRUCTURED_WARNINGS_USER_GUIDE.md`
+  - Test utilities for easy migration (`createMockWarning()`, `WarningCollector`)
+  - Backward compatibility: all new fields optional in `VariantResult`
+
+- **Documentation**:
+  - Complete user guide: `docs/STRUCTURED_WARNINGS_USER_GUIDE.md`
+  - Developer guide with API reference: `docs/STRUCTURED_WARNINGS_DEVELOPER_GUIDE.md`
+  - Warning code reference with troubleshooting steps
+  - Migration checklist and examples
+
+#### Judge System Consolidation
+- **New UnifiedJudge** with strategy pattern (`src/core/judge/unified-judge.ts`)
+  - Replaced 4 judge implementations with single extensible architecture
+  - Code size: Target 93% reduction after v0.3.0 (90KB → ~25KB when deprecated code removed; currently 345KB during deprecation period)
+  - Three built-in strategies: EnhancedJudgeStrategy, StandardJudgeStrategy, ClaudeJudgeStrategy
+  - Factory function `createUnifiedJudge()` for simple instantiation
+  - Full backward compatibility through FacadeJudgeStrategy
+
+#### Standardized Error Hierarchy
+- **38 error types** with standardized hierarchy (`src/types/errors.ts`)
+  - Base: `BuildError` extends `Error` with context fields
+  - System errors: ProviderError, OrchestrationError, JudgeError, TelemetryError, ValidationError
+  - Provider-specific: ProviderTimeoutError, ProviderAuthError, ProviderRateLimitError, etc.
+  - JSON serialization support for all errors
+  - Complete documentation: `docs/reference/error-codes.md`
+
+#### Worktree Resource Pooling
+- **50%+ performance improvement** through pre-warmed worktree pool (`src/orchestrator/worktrees/worktree-pool.ts`)
+  - Pool of 5 pre-created worktrees for instant allocation
+  - Automatic health checks and corruption detection
+  - Concurrency limits prevent resource exhaustion (10 concurrent max)
+  - Graceful degradation when pool exhausted
+
+#### Testing & Validation
+- **82 new integration tests** across critical paths
+  - Complete judge consolidation coverage
+  - Worktree pooling edge cases
+  - Error hierarchy validation
+  - Backward compatibility verification
+  - Test coverage: 80%+ (meets Phase 1 goal)
+
+#### Documentation
+- **Comprehensive migration guides**
+  - Judge consolidation: `docs/migrations/archive/judge-consolidation.md`
+  - Naming changes (Competition → Evaluation): `docs/migrations/archive/naming-v0.2.0.md`
+  - Error code reference: `docs/reference/error-codes.md`
+  - API documentation for UnifiedJudge
+
+### Changed
+
+#### Naming Standardization (Backward Compatible)
+- **Competition → Evaluation** terminology throughout codebase
+- **Variant → Candidate** terminology throughout codebase
+- Full backward compatibility aliases maintain existing APIs
+- Type exports preserve old names for gradual migration
+- Will be removed in v0.3.0 (6-month deprecation period)
+
+#### Improved Worktree Management
+- Consolidated worktree management into resource pool
+- Eliminated duplicate cleanup logic across codebase
+- Better error messages for worktree operations
+- Automatic cleanup on process exit
+
+### Deprecated
+
+#### Judge Implementations (Remove in v0.3.0)
+- **AIJudge** → Use `UnifiedJudge` with `FacadeJudgeStrategy`
+- **AIJudgeEnhanced** → Use `UnifiedJudge` with `EnhancedJudgeStrategy`
+- **AIJudgeFacade** → Use `UnifiedJudge` with `FacadeJudgeStrategy`
+- **ClaudeJudge** → Use `ClaudeJudgeExecutor` from `UnifiedJudge`
+- Runtime deprecation warnings added (suppressible with `SUPPRESS_DEPRECATION_WARNINGS=1`)
+
+#### Naming Changes (Remove in v0.3.0)
+- **Competition types** → Use Evaluation types instead
+- **Variant types** → Use Candidate types instead
+- See migration guide: `docs/migrations/archive/naming-v0.2.0.md`
+
+### Migration Guides
+
+- **Judge consolidation**: All deprecated judges remain functional with runtime warnings
+- **Naming changes**: All old names aliased to new names, no breaking changes
+- **Timeline**: 6-month deprecation period before removal in v0.3.0
+- **Documentation**: Complete migration guides in `docs/migrations/`
+
+### Performance
+
+- **Worktree creation**: 50%+ faster through resource pooling
+- **Judge code size**: Target 93% reduction after v0.3.0 (90KB → ~25KB; currently 345KB during 6-month deprecation period)
+- **Test execution**: 82 new tests with minimal performance impact
+- **Build time**: No regression despite additional type safety
+
+### Changed
+
+### Security
+
+- **Prevent accidental mock/provider shortcuts in production**: add runtime guards, telemetry, and opt-in environment flags (`BUILD_ALLOW_MOCK_PROVIDERS`, `BUILD_ALLOW_PLACEHOLDER_COMMITS`); CI validation added to reject mock flags in production images. (See `docs/MOCK_ENV_VARS.md`)
+
+## [v0.1.0] - 2025-10-29
+
+**Status**:  Production-Ready - All critical features complete and tested
+
+### Added
+
+#### Core Features
+- **Multi-provider orchestration** supporting multiple local CLI providers
+- **Concurrent variant execution** - Run 1-9 competing solutions in parallel across providers and strategies
+- **AI Judge system** with cross-provider comparison and intelligent synthesis of best-performing approaches
+- **Real-time cost tracking** with spike detection, provider recommendations, and budget management
+- **Parallel execution engine** with intelligent batching (3-10x faster than sequential)
+- **Three proven strategies** - Conservative (safe patterns), Innovative (cutting-edge), Hybrid (balanced)
+- **Comprehensive CLI** with 30+ commands for task management, cost monitoring, and telemetry analysis
+
+#### Provider Integrations
+- **Claude (Anthropic)** - Sonnet, Opus, and Haiku models with complete authentication
+- **Codex (GitHub)** - GPT-4 and GPT-5 models with cloud execution and PR workflow
+- **Cursor** - Auto model selection with cloud integration
+- **Gemini (Google)** - 2.5 Flash and 2.5 Pro with auto-batching for efficiency
+
+#### Quality Gates & Validation
+- **Coverage validation** - Enforces configurable thresholds (default 90%)
+- **Linting enforcement** - ESLint integration for code quality
+- **Security scanning** - npm audit and vulnerability detection
+- **Test integration** - Automatic test execution before variant acceptance
+
+#### Telemetry & Analytics
+- **Local SQLite database** persistence for all execution metrics
+- **Variant leaderboard** - Performance rankings by provider and strategy
+- **Prompt effectiveness analysis** - Track which prompts work best for different contexts
+- **Context-aware recommendations** - Suggest best approaches based on language, framework, complexity
+- **Historical trends** - Analyze performance over time
+- **Zero external transmission** - All data stored locally for privacy
+
+#### Developer Experience
+- **Interactive CLI** with progress indicators and real-time status
+- **Configuration framework** for customizing providers, strategies, and quality gates
+- **Template system** for scaffolding new projects
+- **Provider registry** with dynamic pricing information
+- **Environment variable validation** framework for safe configuration
+
+#### Security Enhancements
+- **Cryptographically secure task IDs** - UUID v4 instead of predictable timestamps
+- **Hardened temporary file creation** - Unix permissions (0o700) for secure recursion tracking
+- **Input sanitization** across all CLI commands
+- **Environment variable validation** with type coercion and custom validators
+
+### Fixed
+
+#### Critical Issues (October 28, 2025)
+- **TypeScript compilation** - Resolved 248 TypeScript errors for clean builds
+- **Telemetry persistence** - Fixed SQLite database state isolation issues
+- **Routing telemetry tests** - Corrected test logic for accurate metric collection
+- **Database state isolation** - Implemented test factory for deterministic test execution
+- **Codex cloud retrieval** - Improved queue management and result application
+
+#### Provider-Specific Fixes
+- **Provider registry CLI conflicts** - Renamed command from "providers" to "providers-registry"
+- **Gemini model selection** - Updated default model to gemini-2.5-flash
+- **Memory guardian calibration** - Fine-tuned thresholds for recursion tracking
+- **Provider authentication** - Enhanced timeout handling and error messages
+
+#### Test Suite Improvements
+- **Trend detection logic** - Fixed declining trend detection with proper metric filtering
+- **Mock response sequencing** - Resolved timing-dependent test failures
+- **Database cleanup** - Automatic WAL/SHM file management between tests
+- **Environment setup** - Consistent test database isolation per test
+
+### Changed
+
+#### Architecture & Structure
+- **Telemetry system** - Moved to singleton pattern for shared database instance
+- **Provider loading** - Enhanced model registry with validation
+- **CLI command structure** - Reorganized for clarity and consistency
+- **Configuration validation** - Schema-based environment variable validation
+
+#### Performance Improvements
+- **Parallel execution** - Gemini batching reduces API calls by 70%
+- **Cost tracking** - Optimized queries for real-time monitoring
+- **Telemetry queries** - Improved indexing for faster metric retrieval
+- **Memory usage** - Better resource management for large competition runs
+
+#### Documentation Updates
+- README modernized for v0.1.0 production status
+- Architecture documentation expanded with new components
+- CLI reference guide updated with all 30+ commands
+- Provider setup guide enhanced with authentication walkthroughs
+
+### Security
+
+- **Task ID Generation**: Replaced predictable timestamp-based IDs (`T123456`) with cryptographically secure UUID v4 (128-bit entropy)
+- **Temporary File Permissions**: Hardened with explicit Unix permissions (`0o700`) to prevent unauthorized access
+- **Environment Validation**: Created comprehensive schema-based validation framework
+- **Input Sanitization**: Enhanced across all CLI commands and API endpoints
+- **Dependency Audit**: Regular security scanning with automatic vulnerability detection
+
+### Dependencies
+
+#### Production Dependencies
+- `better-sqlite3@^11.0.0` - Persistent telemetry storage with WAL support
+- `chalk@^5.3.0` - Colored terminal output for CLI
+- `cli-table3@^0.6.5` - Formatted data table display
+- `commander@^12.0.0` - CLI argument parsing and command routing
+- `execa@^9.0.0` - Cross-platform child process execution
+- `ora@^9.0.0` - Elegant CLI spinners and progress indicators
+- `yaml@^2.8.1` - YAML configuration parsing
+- `zod@^4.1.12` - TypeScript-first schema validation
+
+#### Development Dependencies
+- `typescript@^5.4.5` - Latest TypeScript with strict mode
+- `vitest@^3.2.4` - Unit testing framework with coverage instrumentation
+- `@vitest/coverage-v8@^3.2.4` - V8 coverage analysis
+- `tsup@^8.5.0` - Fast TypeScript bundler for production builds
+- `tsx@^4.0.0` - TypeScript execution for development
+- `eslint@^9.38.0` - Code quality and style enforcement
+- `prettier@^3.6.2` - Code formatting
+- `@types/node@^24.10.0` - Node.js type definitions
+
+#### Minimum Requirements
+- Node.js 24.x
+- npm 9.0.0 or higher
+
+### Test Coverage
+
+- **Total Tests**: 362+ tests across all modules
+- **Pass Rate**: 100% with comprehensive coverage
+- **Test Suites**:
+  - Core automation and orchestration (85+ tests)
+  - Provider integrations and authentication (92+ tests)
+  - Telemetry persistence and querying (78+ tests)
+  - Quality gates and validation (56+ tests)
+  - CLI commands and routing (51+ tests)
+
+### Known Limitations
+
+- **Codex Cloud Results**: May require manual `build codex resume --apply` after cloud execution if orchestrator can't apply automatically
+- **Provider Authentication**: Requires external CLI tools (claude-cli for Claude, gh extension for Codex)
+- **Parallel Execution**: Top-level only - nested parallelism not supported to prevent resource exhaustion
+
+### Migration Guide
+
+**For v0.0.x users upgrading to v0.1.0:**
+
+1. **Task IDs**: Existing task IDs format changed from `T123456` to UUID v4. Update any stored references.
+2. **Configuration**: Review `.build-project/config/build.config.js` for new provider options.
+3. **Telemetry Database**: Existing telemetry data remains compatible - no migration required.
+4. **Provider Setup**: New providers require their CLI authentication setup. See [PROVIDER_SETUP.md](docs/PROVIDER_SETUP.md).
+
+### Contributors
+
+- @ebrindley - Initial development and core implementation
+
+---
+
+## Releases
+
+### Development Timeline
+
+- **October 2025**: v0.1.0 stabilization with TypeScript fixes, security hardening, and comprehensive testing
+- **September 2025**: Multi-provider orchestration framework and AI Judge system development
+- **August 2025**: Initial project structure, CLI foundation, and telemetry infrastructure
+
+### Future Roadmap
+
+Planned enhancements for v0.2.0+:
+- Integration with additional AI providers (Anthropic Claude 4, OpenAI GPT-5)
+- Advanced caching strategies for cost optimization
+- Webhook support for CI/CD integration
+- Custom provider plugin system
+- Enhanced metrics and analytics dashboard
+- Machine learning-based strategy recommendations
+
+---
+
+**For questions or issues, visit [GitHub Issues](https://github.com/ebrindley/build/issues)**