@poetic-ai/poetic 1.42.0

package/CHANGELOG.md

@@ -0,0 +1,552 @@
+# Changelog
+
+All notable changes to Poetic 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]
+
+## [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 Poetic through the public `@poetic-ai/poetic` 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 `poetic run "<task>"` now executes the provider from
+  `poetic 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
+  `poetic --help` presents exactly eleven Public roots (`init`, `plan`, `ask`,
+  `run`, `build`, `scan`, `provider`, `config`, `doctor`,
+  `telemetry`, `cleanup`) grouped by four domains. Full help
+  (`poetic --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 Poetic Claude Code plugin product surface. Poetic 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
+  `poetic 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
+  (`.poetic/config/claude-settings.template.json` and its packaged copy
+  `templates/.poetic/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 `.poetic/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 `poetic` plugin manifest (`plugins/poetic/hooks/hooks.json`): the
+  `Stop` session-completion logger, the `Write|Edit` audit logger, the two
+  `Bash(poetic*)` command loggers, and the `Read(*.poetic/reasoning/*.md)`
+  reasoning-gate logger. The Stop logger errored in every Claude Code session
+  whose cwd lacked `.poetic/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` — Poetic's real
+  telemetry is CLI-written (invocations.db, autoloop-history.jsonl). Also
+  removed the dead opt-in auto-format and auto-stage hooks
+  (`POETIC_CLAUDE_AUTO_FORMAT` / `POETIC_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 `poetic run`
+  (`--web`, `--web-api-key`, `--web-endpoint`, `--web-timeout`,
+  `--web-rate-limit`, and the `POETIC_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 Poetic'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 Poetic 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 Poetic'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 `poetic lifecycle track`.
+- Documented true budget behavior. `POETIC_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
+- `poetic 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 `poetic 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):** Poetic'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 and discussions; pull requests are not currently accepted (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 (`~/.poetic/config.json`)
+  - Project-level warning config (`.poetic/warning-config.json`)
+  - Verbosity control via CLI flags (`--warnings verbose|normal|minimal|silent`)
+  - Environment variable support (`POETIC_WARNINGS`, `POETIC_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: `PoeticError` 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
+
+#### GLM Provider - OpenCode-Only Backend
+- **BREAKING**: GLM provider now runs via OpenCode CLI exclusively (Z.ai auth is built-in to OpenCode)
+  - Removed Claude wrapper (`claude-glm*`) execution path and wrapper-specific validation
+  - GLM setup is now: install OpenCode + `opencode auth login` (select Z.AI / Z.AI Coding Plan)
+  - **Rationale**: Reduce complexity and eliminate wrapper-specific drift
+  - **User impact**: If you previously configured `glm.backend=claude` or `POETIC_GLM_BACKEND=claude`, switch to OpenCode
+
+- **Added**: Comprehensive GLM dependency detection and self-healing error messages
+  - `src/core/providers/glm/validation.ts` now checks for OpenCode CLI and prints actionable setup hints
+  - Error messages point to `./scripts/install-glm.sh` for automatic setup
+  - Includes `getProviderDependencyStatus()` and `printProviderDependencyStatus()` for diagnostics
+
+- **Added**: `./scripts/install-glm.sh` - automated installer handling all scenarios
+  - Installs OpenCode CLI
+  - Verifies OpenCode CLI availability
+  - Provides next-step auth instructions (`opencode auth login`)
+
+- **Updated**: Documentation to reflect OpenCode-only GLM
+  - `docs/PROVIDER_SETUP.md` - GLM section + troubleshooting updated
+
+- **CI/CD**: GLM unit tests no longer require Claude wrappers installed
+  - Tests mock CLI execution and validate OpenCode-oriented setup hints
+
+### Security
+
+- **Prevent accidental mock/provider shortcuts in production**: add runtime guards, telemetry, and opt-in environment flags (`POETIC_ALLOW_MOCK_PROVIDERS`, `POETIC_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 Claude, Cursor, Codex, Gemini, and GLM 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
+- **GLM (Zhipu)** - GLM-4 and GLM-4-Vision models
+
+#### 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 `poetic 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 `.poetic/config/poetic.config.js` for new provider options (Gemini, GLM).
+3. **Telemetry Database**: Existing telemetry data remains compatible - no migration required.
+4. **Provider Setup**: New providers (Gemini, GLM) require environment variable 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/Poetic/issues)**

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal attacks
+- Public or private harassment
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Poetic accepts private reports of abusive, harassing, or otherwise
+unacceptable behavior through this repository's GitHub private reporting form.
+Although GitHub labels the form for security advisories, the project also uses
+it as its private conduct-reporting intake:
+
+https://github.com/ebrindley/Poetic/security/advisories/new
+
+Do not put a sensitive conduct report in a public issue. All complaints will be
+reviewed and investigated promptly and fairly.
+
+Project maintainers have the right to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.0.

package/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing to Poetic
+
+Thank you for your interest in Poetic.
+
+## Issues
+
+Bug reports and feature requests through [GitHub Issues](https://github.com/ebrindley/Poetic/issues) are
+encouraged. The more specific the reproduction, the better. For open-ended
+questions, please use [GitHub Discussions](https://github.com/ebrindley/Poetic/discussions).
+
+## Pull requests
+
+Pull requests are welcome. Before starting a large or cross-cutting change,
+open an issue so the scope and direction can be discussed first.
+
+Keep changes focused, follow the repository's `AGENTS.md` instructions, and
+include the smallest meaningful validation for the behavior being changed.
+PR descriptions should state what changed, why, and what validation ran.
+
+## Security
+
+For security issues, please follow [.github/SECURITY.md](./.github/SECURITY.md)
+and don't file them as public issues.