@deriest/ai-engineering-company 1.15.2

package/CHANGELOG.md

@@ -0,0 +1,807 @@
+# Changelog
+
+All notable changes to the AI Engineering Company plugin 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).
+
+## [1.15.2] - 2026-07-05
+
+### Private npm Publication Preparation
+
+No runtime changes. No TypeScript changes.
+
+#### Changed
+
+- **Package scope migration** — Renamed from `@openclaw/ai-engineering-company` to `@deriest/ai-engineering-company` for private npm publishing under the @deriest scope.
+- **Package hardening** — Added `"files"` whitelist to minimize package size (467 files → 237 files, 1,641 KB → 549 KB). Excludes source, docs, scripts, tests, and dev config.
+- **License consistency** — Changed LICENSE from MIT to UNLICENSED to match `"license": "UNLICENSED"` in package.json.
+- **npm publish readiness** — Removed `"private": true`, added `"license": "UNLICENSED"` to package.json.
+
+---
+
+## [1.15.1] - 2026-07-05
+
+### Plugin Metadata Compliance Patch
+
+No runtime changes. No TypeScript changes.
+
+#### Fixed
+
+- **Missing contracts.tools declarations** — Added `ai_company_approve`, `ai_company_reject`, `ai_company_list_approvals` to `openclaw.plugin.json` contracts.tools. These tools were implemented (WP-11, v1.1.0) and registered in both agent tools and gateway, but were not declared in the plugin manifest. `openclaw plugins doctor` now reports zero issues.
+
+---
+
+## [1.15.0] - 2026-07-05
+
+### Pipeline Task State & Error Propagation Fixes [WP-25]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Fixed
+
+- **Defect #1 — Task state initialization on resume** — `resumePipeline()` now creates a task state entry via `taskState.create()` before calling `executePipeline()`. Without this, all task state transitions during the resumed pipeline silently failed (returned `null`) because `TaskStateManager.get()` returned `undefined` for unknown session keys. (`src/dispatch-service.ts:resumePipeline()`)
+- **Defect #2 — Pipeline failure error propagation** — `executePipeline()` now captures the per-stage error message (`result.error`) when a stage fails, and includes it in both the returned `DispatchResult.error` string and the `pipelineCheckpoint.fail()` reason. Previously, the error said "Pipeline failed at stage N" with no indication of what went wrong. (`src/dispatch-service.ts:executePipeline()`)
+- **Pipeline mode for executeStage()** — Added `pipelineMode` parameter (default `false`) to `executeStage()`. When `true`, all 5 task state transitions inside executeStage are skipped, and the pipeline loop manages state directly. This prevents `executeStage()` from transitioning to `"completed"` (a terminal state) after each stage, which blocked subsequent stages from transitioning to `"running"`. (`src/dispatch-service.ts:executeStage()`)
+
+#### Changed
+
+- **`executeStage()` signature** — Extended with optional `pipelineMode` parameter (6th param, default `false`). Public API unchanged; existing callers unaffected. (`src/dispatch-service.ts`)
+- **`executePipeline()` call site** — Passes `pipelineMode: true` to `executeStage()` for all pipeline stage executions. (`src/dispatch-service.ts`)
+
+#### Design
+
+- **Minimal diff** — 3 targeted changes in a single file. No new modules, no interface changes, no dependency additions.
+- **Backward compatible** — `pipelineMode` defaults to `false`, preserving existing standalone dispatch behavior.
+- **Root cause** — `executeStage()` was shared between standalone and pipeline contexts. Terminal task state transitions (`completed`) in pipeline context blocked the pipeline loop's state management.
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors
+- `npx vitest run` — 351 tests pass (23 files), zero failures
+- B3 re-validation: Q3 and Q6 now PASS (were FAIL). Q1, Q2, Q4, Q5, Q7 unchanged (no regression).
+- Full verification checklist: 8/8 PASS
+
+---
+
+## [1.14.0] - 2026-07-05
+
+### Distributed Foundation [WP-24]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Added
+
+- **RedisQueueBackend** — Redis-backed QueueBackend implementation using hashes + sets. All methods async, returns `Promise<T>`. (`src/redis-queue-backend.ts`)
+- **RedisLeaseProvider** — Redis-backed LeaseProvider using SET NX EX for atomic acquire with TTL. Ownership validation on renew/release. (`src/redis-lease-provider.ts`)
+- **Promise-only backend interfaces** — All `QueueBackend` and `LeaseProvider` methods return `Promise<T>`. No union types. (`src/queue-backend.ts`, `src/lease-provider.ts`)
+- **Memory implementations with `Promise.resolve()`** — MemoryQueueBackend, MemoryLeaseProvider, FileQueueBackend wrap sync logic in `Promise.resolve()`. (`src/memory-queue-backend.ts`, `src/memory-lease-provider.ts`, `src/file-queue-backend.ts`)
+- **Optional Redis activation** — Redis enables via `AI_COMPANY_REDIS_URL` env var or `config.redis.url`. Falls back to memory on failure. (`src/index.ts`)
+- **Node identity resolution** — `nodeId` resolved from `config.nodeId` or `os.hostname()` at startup. (`src/index.ts`)
+- **Redis backend tests** — 29 tests covering RedisQueueBackend, RedisLeaseProvider, nodeId resolution, activation, fallback. (`src/redis-backends.test.ts`)
+
+#### Changed
+
+- **QueueBackend interface** — All methods return `Promise<T>` (was sync or union types). (`src/queue-backend.ts`)
+- **LeaseProvider interface** — All methods return `Promise<T>` (was sync or union types). (`src/lease-provider.ts`)
+- **DecisionQueue** — All methods `async`, uses `await` for backend calls. (`src/decision-queue.ts`)
+- **DispatchService** — Constructor accepts `leaseProvider` and `nodeId`. Lease operations use `this.nodeId`. (`src/dispatch-service.ts`)
+- **Composition root** — Memory remains default. Redis activates when configured. Fallback on failure. (`src/index.ts`)
+- **All consumers** — CLI, Gateway, Agent Tools use `async/await` consistently. (`src/cli.ts`, `src/gateway.ts`, `src/tools.ts`)
+- **All test files** — Updated to use `async/await` for Promise-returning methods.
+
+#### Design
+
+- **Promise-only** — No union return types, no sync adapters, no fire-and-forget.
+- **Optional Redis** — Zero-config default (memory). Redis activates only when configured.
+- **Graceful fallback** — Redis connection failure falls back to memory mode at startup.
+- **Node identity** — Resolved once at startup. Not persisted. Not registered.
+- **No scope expansion** — No Pub/Sub, heartbeat, leader election, distributed metrics, cluster management.
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors
+- `npx vitest run` — 351 tests pass (23 files), zero failures
+- Zero regressions. All existing behavior unchanged.
+
+---
+
+## [1.13.0] - 2026-07-04
+
+### OpenClaw Identity Integration [WP-23]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Added
+
+- **Verified operator identity for gateway approvals** — Gateway `approve` and `reject` handlers now resolve operator identity from SDK-provided `client` parameter. Resolution order: `client.connect.client.displayName` → `client.connId` → `params.operator` (fallback). (`src/gateway.ts`)
+- **`resolveOperator()` helper** — Private function implementing the fallback chain. (`src/gateway.ts`)
+- **Identity resolution tests** — 5 tests covering: displayName priority, connId fallback, null client fallback, no identity fallback, reject handler. (`src/gateway.test.ts`)
+
+#### Changed
+
+- **Gateway `approve` handler** — Destructures `client` from handler options. (`src/gateway.ts`)
+- **Gateway `reject` handler** — Same identity resolution as approve. (`src/gateway.ts`)
+
+#### Design
+
+- **SDK-first** — Uses OpenClaw verified identity model. No plugin-level auth or RBAC.
+- **Backward compatible** — Falls back to self-reported `params.operator` when client is null or lacks identity.
+- **Audit propagation** — Verified identity flows through existing DecisionQueue → EventEmitter → AuditLogger pipeline unchanged.
+
+#### Verification
+
+- Build: `tsc --noEmit` clean
+- Tests: 322 passed (22 files)
+- No scope, API, or interface changes
+
+## [1.12.0] - 2026-07-04
+
+### Operator-Assisted Pipeline Resume [WP-22]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Added
+
+- **`resumePipeline()` method** — Resumes an interrupted pipeline from its last checkpoint. Reconstructs `StagePlan[]` from checkpoint stages, slices at `currentStageIndex`, restores execution history, and delegates to `executePipeline()`. Preserves original objective. (`src/dispatch-service.ts`)
+- **`recover --resume` option** — CLI command `openclaw ai-company recover --resume <sessionKey>` resumes an interrupted pipeline from checkpoint. Validates checkpoint exists, calls `resumePipeline()`, outputs result. (`src/cli.ts`)
+- **Startup `awaiting_approval` re-enqueue** — On startup, `awaiting_approval` checkpoints are re-enqueued into `DecisionQueue` if not already present. Operators see pending approvals without re-dispatching. (`src/index.ts`)
+- **Pipeline resume tests** — 5 new tests covering: resume from checkpoint skipping completed stages, history preservation, missing worker error, missing dispatcher error, existing dispatch path unchanged. (`src/dispatch-service.test.ts`)
+
+#### Changed
+
+- **`executePipeline()` signature** — Extended with optional `resumeHistory` parameter for injecting restored stage history. (`src/dispatch-service.ts`)
+- **`AiCompanyCliDeps.dispatchService`** — Pick type extended with `resumePipeline`. (`src/cli.ts`)
+
+#### Design
+
+- **Operator-assisted** — No automatic resume. Operator explicitly triggers via `recover --resume`.
+- **Stage idempotency** — All 6 pipeline stages are safe to re-execute. `subagent.run()` uses `deliver: false` and produces only text output. New `runId` each call.
+- **History restoration** — Completed stage outputs restored from `checkpoint.history[]`. New stages append to restored history.
+- **Lease lifecycle** — Resume acquires/releases lease identically to normal dispatch through `executePipeline()`.
+- **Audit** — Single `pipeline_started` event emitted by `executePipeline()`. No duplicate events.
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors
+- `npx vitest run` — 320 tests pass (22 files), zero failures
+- Zero regressions. All existing behavior unchanged
+
+---
+
+## [1.11.0] - 2026-07-04
+
+### Queue Backend Abstraction [WP-21]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Added
+
+- **QueueBackend interface** — Abstracts storage for DecisionQueue. Operations: `enqueue`, `get`, `list`, `update`, `remove`, `load`, `save`, `trySave`, `cleanup`. (`src/queue-backend.ts`)
+- **QueueEntry, QueueEvent, QueueEntryUpdate types** — Shared data types for queue operations. (`src/queue-backend.ts`)
+- **MemoryQueueBackend** — Default in-memory QueueBackend implementation. Map-based storage with JSON file persistence and atomic write (.tmp + rename). (`src/memory-queue-backend.ts`)
+- **FileQueueBackend** — JSON file-backed QueueBackend implementation. Same semantics as MemoryQueueBackend, distinct class for future differentiation. (`src/file-queue-backend.ts`)
+- **LeaseProvider interface** — Abstracts ownership leasing for pipeline execution. Operations: `acquire`, `renew`, `release`, `get`, `cleanup`. (`src/lease-provider.ts`)
+- **Lease type** — Lease record with `sessionKey`, `nodeId`, `acquiredAt`, `expiresAt`. (`src/lease-provider.ts`)
+- **MemoryLeaseProvider** — Default in-memory LeaseProvider with TTL expiration and ownership validation. (`src/memory-lease-provider.ts`)
+- **Lease lifecycle in DispatchService** — `acquire()` at pipeline start, `release()` on success/failure/rejection. Audit events emitted on failure. (`src/dispatch-service.ts`)
+- **Audit events** — `lease_acquire_failed` and `lease_release_failed` for lease lifecycle observability. (`src/audit-logger.ts`)
+
+#### Changed
+
+- **DecisionQueue** — Delegates storage to QueueBackend. Constructor: `(metrics?, backend?)`. Default backend: MemoryQueueBackend. EventEmitter preserved. (`src/decision-queue.ts`)
+- **DecisionEntry** — Now a type alias for QueueEntry (backward compatible). (`src/decision-queue.ts`)
+- **DecisionEvent** — Now a type alias for QueueEvent (backward compatible). (`src/decision-queue.ts`)
+- **DispatchService** — Added optional `leaseProvider` constructor parameter. (`src/dispatch-service.ts`)
+- **Composition root** — Instantiates MemoryQueueBackend, MemoryLeaseProvider and injects through constructors. (`src/index.ts`)
+
+#### Preserved
+
+- All existing DecisionQueue public APIs unchanged
+- All existing PipelineCheckpoint behavior unchanged (WP-20 implementation restored)
+- FCFS semantics preserved
+- EventEmitter event behavior preserved
+- Persistence behavior preserved
+- No external dependencies added
+- No Redis, PostgreSQL, SQLite, or distributed networking
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors
+- `npx vitest run` — 315 tests pass (22 files), zero failures
+- Zero regressions. All external behavior unchanged
+
+---
+
+## [1.10.0] - 2026-07-04
+
+### Pipeline Checkpoint [WP-20]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Note
+
+WP-20 implementation was developed alongside WP-21 and restored as part of the Queue Backend Abstraction milestone. The PipelineCheckpoint module (`src/pipeline-checkpoint.ts`) provides stage-level crash recovery persistence with atomic JSON writes, following the same persistence pattern as DecisionQueue.
+
+#### Added
+
+- **`PipelineCheckpoint`** — Stage-level crash recovery persistence. Atomic JSON write. (`src/pipeline-checkpoint.ts`)
+- **`PipelineCheckpointEntry` interface** — Typed checkpoint with sessionKey, objective, category, stage index, stage definitions, execution history, status, decidedBy, and timestamps. (`src/pipeline-checkpoint.ts`)
+- **Checkpoint lifecycle** — `set()` after stage completion and approval acceptance, `fail()` on rejection/stage failure, `complete()` on pipeline success. (`src/dispatch-service.ts`)
+- **Startup detection** — Loads persisted checkpoints, logs count of interrupted pipelines. (`src/index.ts`)
+- **Startup cleanup** — `cleanup(24h)` removes stale `failed`/`completed` entries; preserves `running`/`awaiting_approval`. (`src/index.ts`)
+- **`openclaw ai-company recover`** — CLI command listing interrupted pipelines with sessionKey, objective, category, stage progress, and timestamps. (`src/cli.ts`)
+- **Lifecycle safeguard** — `pipelineCheckpoint.save()` on application shutdown. (`src/index.ts`)
+
+#### Changed
+
+- **`DispatchService`** — Constructor extended with optional `PipelineCheckpoint` parameter. `executePipeline()` writes checkpoints at approved boundaries. (`src/dispatch-service.ts`)
+- **`AiCompanyCliDeps`** — Extended with optional `pipelineCheckpoint` property. (`src/cli.ts`)
+- **Composition root** — PipelineCheckpoint instantiated, loaded, scanned, cleaned, and passed to DispatchService and CLI. (`src/index.ts`)
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 241 tests pass (18 suites), zero failures.
+- Zero regressions. All external behavior unchanged.
+
+---
+
+## [1.9.0] - 2026-07-04
+
+### Multi-user Approval [WP-19]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Added
+
+- **Operator attribution on approve/reject** — `DecisionEntry.operator?: string` and `DecisionEvent.operator?: string` store and emit the identity of the operator who made the decision. (`src/decision-queue.ts`)
+- **`approve(sessionKey, operator?, reason?)`** — Extended signature accepts optional operator parameter. Stores `entry.operator` and includes operator in emitted event. (`src/decision-queue.ts`)
+- **`reject(sessionKey, operator?, reason?)`** — Extended signature accepts optional operator parameter. Stores `entry.operator` and includes operator in emitted event. (`src/decision-queue.ts`)
+- **Gateway operator support** — `ai-company.approve` and `ai-company.reject` accept optional `operator` parameter and pass it to DecisionQueue. (`src/gateway.ts`)
+- **CLI `--operator` flag** — `approve` and `reject` commands accept `--operator <name>` option. (`src/cli.ts`)
+- **Agent tool operator parameter** — `ai_company_approve` and `ai_company_reject` tool schemas extended with optional `operator` field. (`src/tools.ts`)
+- **AuditLogger `operator` field** — `AuditEvent.operator?: string` records operator identity on approved/rejected events. (`src/audit-logger.ts`)
+- **PipelineCheckpoint `decidedBy` field** — `PipelineCheckpointEntry.decidedBy?: string` records which operator made the approval decision. (`src/pipeline-checkpoint.ts`)
+- **Audit event forwarding** — DecisionQueue decision events forwarded to AuditLogger with operator. (`src/index.ts`)
+- **DispatchService operator propagation** — `waitForDecision()` return type includes `operator`; propagated to checkpoint writes. (`src/dispatch-service.ts`)
+
+#### Changed
+
+- **`DecisionEntry`** — Added `operator?: string` field. (`src/decision-queue.ts`)
+- **`DecisionEvent`** — Added `operator?: string` field. (`src/decision-queue.ts`)
+- **`AuditEvent`** — Added `operator?: string` field. (`src/audit-logger.ts`)
+- **`PipelineCheckpointEntry`** — Added `decidedBy?: string` field. (`src/pipeline-checkpoint.ts`)
+- **`DispatchService.waitForDecision()`** — Return type extended with `operator?: string`. (`src/dispatch-service.ts`)
+
+#### Preserved
+
+- FCFS semantics: first decision wins, `null` returned for already-decided entries
+- All existing API response contracts unchanged
+- No new response statuses or response fields
+- Existing test patterns preserved
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 254 tests pass (18 suites), zero failures.
+- Zero regressions. All external behavior unchanged. Operator is purely additive (`?: string`).
+
+---
+
+## [1.8.0] - 2026-07-04
+
+### Runtime Recovery [WP-18]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Gate 3**: PASS
+
+#### Added
+
+- **`PipelineCheckpoint`** — Stage-level crash recovery persistence. Atomic JSON write, follows DecisionQueue pattern. (`src/pipeline-checkpoint.ts`)
+- **`PipelineCheckpointEntry` interface** — Typed checkpoint with sessionKey, objective, category, stage index, stage definitions, execution history, status, and timestamps. (`src/pipeline-checkpoint.ts`)
+- **Checkpoint write after stage completion** — After `history.push()` and `stage_completed` audit event. (`src/dispatch-service.ts`)
+- **Checkpoint write after approval acceptance** — After `decisionQueue.remove()` and `taskState.transition("running")`. (`src/dispatch-service.ts`)
+- **Checkpoint `.fail()` on rejection** — Pipeline rejection persists failure reason. (`src/dispatch-service.ts`)
+- **Checkpoint `.fail()` on stage failure** — Pipeline stage failure persists error. (`src/dispatch-service.ts`)
+- **Checkpoint `.complete()` on pipeline success** — Removes checkpoint from persistence. (`src/dispatch-service.ts`)
+- **Startup detection** — Loads persisted checkpoints, logs count of interrupted pipelines. (`src/index.ts`)
+- **Startup cleanup** — `cleanup(24h)` removes stale `failed`/`completed` entries; preserves `running`/`awaiting_approval`. (`src/index.ts`)
+- **`openclaw ai-company recover`** — CLI command listing interrupted pipelines with sessionKey, objective, category, stage progress, and timestamps. (`src/cli.ts`)
+- **Lifecycle safeguard** — `pipelineCheckpoint.save()` on application shutdown alongside `decisionQueue.save()`. (`src/index.ts`)
+
+#### Changed
+
+- **`DispatchService`** — Constructor extended with optional `PipelineCheckpoint` parameter (12th param). `executePipeline()` writes checkpoints at approved boundaries. (`src/dispatch-service.ts`)
+- **`AiCompanyCliDeps`** — Extended with optional `pipelineCheckpoint` property. (`src/cli.ts`)
+- **Composition root** — PipelineCheckpoint instantiated, loaded, scanned, cleaned, and passed to DispatchService and CLI. (`src/index.ts`)
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 241 tests pass (18 suites), zero failures.
+- Zero regressions. All external behavior unchanged. PipelineCheckpoint is optional dependency (`?.` calls).
+
+---
+
+## [1.7.0] - 2026-07-04
+
+### Technical Debt Resolution [WP-17]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Added
+
+- **TaskState transition validation** — `VALID_TRANSITIONS` map enforces state machine. Invalid transitions return `null` instead of silently allowing. (`src/task-state.ts`)
+- **Approval timeout** — Configurable `approvalTimeoutMs` (default 30 min) prevents pipeline hangs. Timeout returns `approval_timeout` reason. (`src/dispatch-service.ts`)
+- **DecisionQueue startup cleanup** — `cleanup(maxAgeMs)` removes expired pending entries on startup. Sequence: `load()` → `cleanup(24h)` → `save()`. No events emitted, no audit generated, no task state transitions. (`src/decision-queue.ts`, `src/index.ts`)
+- **Audit retention** — `cleanup(maxAgeDays)` removes old JSONL files (default 30 days). Silent I/O failure handling. (`src/audit-logger.ts`)
+- **Audit query CLI** — `openclaw ai-company audit` command with filters: `--session`, `--event`, `--source`, `--from`, `--to`. Skips malformed JSONL lines. CLI-only, no Gateway RPC. (`src/cli.ts`, `src/audit-logger.ts`)
+- **Legacy test cleanup** — Moved 4 unique tests from `src/__tests__/` to `src/`. Deleted 16 broken duplicate test files. All imports corrected.
+
+#### Changed
+
+- **TaskStateManager** — `transition()` now validates against `VALID_TRANSITIONS` map. Invalid transitions return `null`. Valid transitions unchanged. (`src/task-state.ts`)
+- **DispatchService** — Constructor extended with `approvalTimeoutMs` parameter (11th param). `waitForDecision()` uses `Promise.race` with timeout. (`src/dispatch-service.ts`)
+- **AuditLogger** — Extended with `cleanup(maxAgeDays)` and `query(filter)` methods. (`src/audit-logger.ts`)
+- **CLI** — `AiCompanyCliDeps` extended with optional `auditLogger`. New `audit` subcommand. (`src/cli.ts`)
+- **Composition root** — DecisionQueue startup cleanup wired. AuditLogger passed to CLI registration. (`src/index.ts`)
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 241 tests pass (18 suites).
+- Zero regressions. All external behavior unchanged.
+
+---
+
+## [1.6.0] - 2026-07-04
+
+### Audit Logging [WP-16]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Added
+
+- **`AuditLogger`** — Append-only JSONL writer with silent I/O failure handling. Writes to `.openclaw/audit/audit-YYYY-MM-DD.jsonl`. (`src/audit-logger.ts`)
+- **`AuditEvent` interface** — Typed audit event with common fields (ts, sessionKey, event) and optional context fields (source, worker, stage, decisionStatus, reason, etc.). (`src/audit-logger.ts`)
+- **`AuditEventType` union** — 13 approved event types: dispatch_requested, plan_created, task_created, pipeline_started, stage_started, approval_requested, approved, rejected, stage_completed, stage_failed, pipeline_completed, pipeline_failed, dispatch_completed. (`src/audit-logger.ts`)
+- **`DispatchSource` type** — Source tagging enum: gateway, cli, tool, command. (`src/audit-logger.ts`)
+- **DispatchService instrumentation** — Optional `auditLogger` constructor parameter. Writes audit events at all approved lifecycle points. (`src/dispatch-service.ts`)
+- **Source tagging** — Optional `source` parameter on `dispatch()` method. Entry points pass source: gateway, cli, tool, command. (`src/dispatch-service.ts`, `src/gateway.ts`, `src/cli.ts`, `src/tools.ts`, `src/commands/aicompany.ts`)
+- **DecisionQueue event subscription** — Composition root subscribes to DecisionQueue "decision" event. Writes approved/rejected audit events. (`src/index.ts`)
+- **Audit logger tests** — 8 new tests covering: valid JSON, append behavior, JSONL parsing, directory creation, silent failure, field round-trip, date-based filename, all event types. Total: 236 tests.
+
+#### Changed
+
+- **`DispatchService`** — Extended with optional `auditLogger` constructor parameter (10th param). `dispatch()` method accepts optional `source` parameter (3rd arg). (`src/dispatch-service.ts`)
+- **Composition root** — `AuditLogger` instantiated at `.openclaw/audit`. Passed to `DispatchService`. DecisionQueue event subscription wired. (`src/index.ts`)
+- **Entry points** — Gateway, CLI, Tools, Command now pass `source` parameter to `dispatch()`. (`src/gateway.ts`, `src/cli.ts`, `src/tools.ts`, `src/commands/aicompany.ts`)
+- **Test assertions** — Fixed 5 test assertions in `cli.test.ts`, `tools.test.ts`, `commands/aicompany.test.ts` to expect 3-arg `dispatch()` calls.
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 236 tests pass. 11 pre-existing `src/__tests__/` failures unrelated to WP-16.
+- Zero regressions. All external behavior unchanged.
+
+---
+
+## [1.5.0] - 2026-07-04
+
+### DecisionQueue Persistence [WP-15]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Added
+
+- **`DecisionQueue.load(filePath)`** — Instance method that hydrates pending entries from a JSON file. No-op on missing or corrupt file. (`src/decision-queue.ts`)
+- **`DecisionQueue.save(filePath?)`** — Instance method that persists pending entries to a JSON file using atomic write (`.tmp` + `rename`). No-op if no file path configured. (`src/decision-queue.ts`)
+- **Automatic persistence** — `enqueue()`, `approve()`, `reject()`, and `remove()` now auto-save after every mutation. (`src/decision-queue.ts`)
+- **Persistence store path** — `rootDir/.openclaw/decisions.json`. (`src/index.ts`)
+- **Lifecycle safeguard** — Best-effort `save()` on application shutdown. (`src/index.ts`)
+- **Persistence tests** — 11 new tests covering: save/load round-trip, non-pending exclusion, missing file, corrupt JSON, auto-save after all mutations, no-op without path, parent directory creation. Total: 228 tests.
+
+#### Changed
+
+- **`DecisionQueue`** — Extended with `filePath` private field, `load()`, `save()`, and `trySave()` methods. Constructor signature unchanged. (`src/decision-queue.ts`)
+- **Composition root** — `DecisionQueue` constructed then loaded from persistence path. Lifecycle cleanup calls `save()`. (`src/index.ts`)
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 228 tests pass. 11 pre-existing `src/__tests__/` failures unrelated to WP-15.
+- Zero regressions. All external behavior unchanged.
+
+---
+
+## [1.4.0] - 2026-07-04
+
+### Gateway RPC [WP-14]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Added
+
+- **`ai-company.list_approvals`** — Gateway method (scope: `operator.read`) listing pending approval requests. Returns count and entry list. (`src/gateway.ts`)
+- **`ai-company.approve`** — Gateway method (scope: `operator.write`) approving a pending task by sessionKey. Optional `reason` parameter. Returns `not_found` for unknown/already-decided entries. (`src/gateway.ts`)
+- **`ai-company.reject`** — Gateway method (scope: `operator.write`) rejecting a pending task by sessionKey. Optional `reason` parameter. Returns `not_found` for unknown/already-decided entries. (`src/gateway.ts`)
+- **Gateway tests** — 9 new tests in `src/__tests__/gateway.test.ts` covering list_approvals, approve, reject, missing parameters, and unknown sessions. Total: 217 tests.
+
+#### Changed
+
+- **`AiCompanyGatewayDeps`** — Extended with optional `decisionQueue` property. (`src/gateway.ts`)
+- **Composition root** — DecisionQueue wired into Gateway registration. (`src/index.ts`)
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 217 tests pass. 12 pre-existing `src/__tests__/` failures unrelated to WP-14.
+- Zero regressions. External behavior unchanged.
+
+---
+
+## [1.3.0] - 2026-07-04
+
+### Event-driven DecisionQueue [WP-13]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Changed
+
+- **DecisionQueue** — Extended with Node.js `EventEmitter`. Emits `"decision"` event when `approve()` or `reject()` is called. (`src/decision-queue.ts`)
+- **DecisionEvent interface** — New exported type: `{sessionKey, status, reason}`. (`src/decision-queue.ts`)
+- **DispatchService.waitForDecision()** — Replaced 500ms polling loop with event-driven Promise. Listens for `"decision"` event filtered by sessionKey. Removes listener after resolution. Race-condition guard checks existing status before listening. (`src/dispatch-service.ts`)
+
+#### Added
+
+- **Event emission tests** — 4 new tests in `decision-queue.test.ts` covering approve event, reject event, and idempotency guards.
+
+#### Removed
+
+- **Polling loop** — `while(true)` + `setTimeout(500)` polling in `waitForDecision()` eliminated.
+
+#### Verification
+
+- `npx tsc --noEmit` — zero TypeScript errors.
+- `npx vitest run` — 199 tests pass. 12 pre-existing `src/__tests__/` failures unrelated to WP-13.
+- Zero regressions. External behavior unchanged.
+
+---
+
+## [1.2.0] - 2026-07-04
+
+### Production Validation [WP-12]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+**Validation Result**: PARTIAL PASS
+
+#### Validated
+
+- **Level 1 — Static Validation** — Build passes with zero errors. Typecheck passes. 195 tests pass across 17 executable test suites.
+- **Level 2 — Integration Validation** — All components validated: Dispatcher (classification + worker selection), Pipeline (6 stages), DecisionQueue (6 operations), TaskStateManager (6 states), CLI (6 subcommands), Agent Tools (6 tools), Worker Health (10 workers).
+- **Level 3 — Runtime Validation** — BLOCKED. Runtime environment (OpenClaw instance) not available. Deferred until runtime is provided.
+
+#### Verification
+
+- Phase 3 verification completed. All evidence verified against repository state.
+- No implementation occurred during validation.
+- No architecture changes introduced.
+- No scope expansion.
+
+#### Documentation
+
+- CHANGELOG updated with Production Validation results.
+- CHECKPOINT updated with validation status.
+- Technical notes documented in docs/WP-12-PRODUCTION-VALIDATION.md.
+
+---
+
+## [1.1.0] - 2026-07-04
+
+### Human-in-the-Loop Approval [WP-11]
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Added
+
+- **DecisionQueue** — In-memory queue for operator approval decisions. Supports enqueue, approve, reject, get, list, and remove operations. (`src/decision-queue.ts`)
+- **Approval Gate** — Pipeline stages following the approval gate (after VERIFY) pause for operator approval when `requiresApproval` is set on the StagePlan. (`src/dispatch-service.ts`)
+- **StagePlan.requiresApproval** — Boolean flag on StagePlan indicating whether a stage requires operator approval before execution. Set by Dispatcher when the task category has an approval gate defined in ROUTING.md. (`src/dispatcher.ts`)
+- **`awaiting_approval` task state** — New task state between `running` and `completed`/`failed`. Task transitions to this state while waiting for operator decision. (`src/task-state.ts`)
+- **CLI approval commands** — `openclaw ai-company approvals` (list pending), `openclaw ai-company approve <sessionKey>`, `openclaw ai-company reject <sessionKey>`. (`src/cli.ts`)
+- **Agent approval tools** — `ai_company_approve`, `ai_company_reject`, `ai_company_list_approvals` for operator-facing approval via agent interface. (`src/tools.ts`)
+- **ROUTING.md approval gates** — Policy section defining which task types require operator approval after which stage. Currently: `engineering` and `security_review` require approval after VERIFY. (`assets/workers/dispatcher/ROUTING.md`)
+- **`decision-queue.test.ts`** — 9 unit tests covering full DecisionQueue lifecycle.
+- **`dispatcher-approval.test.ts`** — 3 tests covering approval gate classification and StagePlan flag.
+
+#### Changed
+
+- `Dispatcher.classify()` — `add`, `implement`, `feature`, `build` keywords now classify as `engineering` (unified with existing engineering classification). `security_review` remains a distinct classification for security-related keywords.
+- `Dispatcher.createPlan()` — Iterates pipeline stages and sets `requiresApproval: true` on stages following the approval gate.
+- `DispatchService` constructor — Accepts optional `DecisionQueue` dependency.
+- `DispatchService.executePipeline()` — Checks `stagePlan.requiresApproval` before each stage; if set, transitions task to `awaiting_approval`, enqueues decision, and waits for operator response.
+- `index.ts` — Wires DecisionQueue into DispatchService, CLI, and agent tools.
+- `cli.ts` — `AiCompanyCliDeps` interface extended with optional `DecisionQueue`.
+- `tools.ts` — `AiCompanyToolsDeps` interface extended with optional `DecisionQueue`.
+
+#### Deferred
+
+- ~~Event-driven decision notification~~ **COMPLETE (WP-13, v1.3.0)**
+- ~~Gateway RPC for approval operations~~ **COMPLETE (WP-14, v1.4.0)**
+- Persistence for DecisionQueue
+- Timeout/expiration for pending approvals
+- Audit logging
+- Multi-user approval
+
+#### Verification
+
+- `npx tsc` — zero TypeScript errors.
+- `npx vitest run` — 195 tests pass (17 suites). 12 pre-existing `src/__tests__/` failures unrelated to WP-11.
+- Zero regressions in existing functionality.
+
+---
+
+## [1.0.1] - 2026-07-04
+
+### Pipeline Execution & UX Polish
+
+**Status**: CLOSED
+**Baseline**: bf70639 (v1.0.0)
+
+#### Fixed
+
+- **Multi-stage pipeline execution** [WP-10] — `DispatchService` now executes all 6 pipeline stages (INTAKE → UNDERSTAND → PLAN → BUILD → VERIFY → SHIP) instead of only `plan.stages[0]`.
+- **Context accumulation** [WP-10] — Each stage receives the original task plus full output history of all preceding stages. `buildStageMessage()` constructs structured context with original task, pipeline history, current stage, and worker assignment.
+- **Pipeline failure handling** [WP-10] — Stages that error or timeout abort the pipeline immediately with proper error propagation and duration reporting.
+- **Task state machine** [WP-10] — `executeStage()` now transitions task state through `submitted → completed | failed` for both single-stage and pipeline paths. Previously state was never advanced beyond `created`.
+
+#### Changed
+
+- **UX output format** [WP-9] — `/aicompany` slash command displays company branding (`🏢 AI Engineering Company`), capitalized task, "Assigned To" with worker name, status label, duration, error details, and worker response with separator.
+- **Command handler DI** [WP-9] — `handleAiCompanyCommand()` accepts optional `dispatcher` dependency for routing display. Backward-compatible degraded mode without dispatcher.
+- **README.md** [WP-9] — Rewritten with Quick Start, `/aicompany` documentation, example output format, config options table.
+- Pipeline execution forces `wait: true` for multi-stage runs (context chaining requires each stage's output).
+- `executePipeline()` and `executeStage()` refactored to dedicated methods.
+
+#### Added
+
+- **`aicompany.test.ts`** [WP-9] — 8 tests covering dispatch formatting, error handling, whitespace trimming, degraded mode, capitalization.
+- `buildStageMessage()`, `extractStageOutput()` — pipeline context assembly functions.
+
+#### Verification
+
+- `npm run build` — zero TypeScript errors.
+- `npm test` — 101 tests pass (7 suites).
+- `npm run typecheck` — clean.
+- Single-stage dispatch unchanged (no regression).
+- Pipeline dispatch executes all stages with accumulated context.
+
+#### Historical Note
+
+> During development, "WP-9.1" was temporarily used as an intermediate tracking label for UX and documentation improvements. Under the current engineering workflow, sub-work-packages are no longer used. WP-9.1 is therefore considered part of WP-9 and is not treated as an independent Work Package.
+
+---
+
+## [1.0.0] - 2026-07-04
+
+### OpenClaw Plugin Integration — COMPLETE
+
+**Status**: CLOSED
+**Architecture**: FROZEN (ADR-001)
+**Baseline**: ad2e23c (v1.0.0)
+
+#### Changed
+
+- **Plugin SDK Migration** — Replaced `@openclaw/plugin-sdk` stub with official `openclaw` devDependency. Plugin consumes SDK via subpath exports.
+- **Module Resolution** — TypeScript `module: "NodeNext"`, `moduleResolution: "NodeNext"`. All relative imports use `.js` extensions.
+- **Build Configuration** — Added `rootDir: "./src"` to tsconfig. Output path fixed from `dist/src/` to `dist/`.
+- **Gateway Error Handling** — All gateway error responses include required `code` property.
+- **Session API Alignment** — `getSessionEntry` parameter aligned to `{ sessionKey }`.
+- **Lifecycle Registration** — Uses `api.lifecycle.registerRuntimeLifecycle()`.
+
+#### Fixed
+
+- `AgentToolResult` import from `openclaw/plugin-sdk/agent-core`.
+- Gateway error objects include `code` field (INVALID_PARAMS, INTERNAL_ERROR, DISPATCH_ERROR, STATUS_ERROR, RESULT_ERROR).
+- `DispatchService.getSessionEntry` parameter corrected to `{ sessionKey }`.
+
+#### Verification
+
+- `npm run build` — zero TypeScript errors.
+- `openclaw plugins build` — succeeds.
+- `openclaw plugins validate` — valid.
+- `openclaw plugins install --link` — installs successfully.
+- Gateway loads plugin, lists in `openclaw plugins list` (enabled).
+- 14 test suites pass, 175 tests pass.
+
+#### Known Limitations (updated)
+
+- ~~`@openclaw/plugin-sdk` not published to npm~~ **RESOLVED**.
+- 12 pre-existing `src/__tests__/` failures (`.js` extension in Vitest, equivalent `src/` tests pass).
+
+---
+
+## [0.9.0] - 2026-07-03
+
+### Knowledge-Runtime Alignment Milestone — COMPLETE
+
+**Status**: CLOSED
+**Architecture**: FROZEN (ADR-001)
+**Baseline**: ad2e23c (v0.8.0)
+
+#### Added
+
+- **WP-01: Office ID Normalization** — Removed `office_` prefix from office identifiers. Offices now use bare IDs: `product`, `engineering`, `governance`.
+- **WP-02: Worker Config Generation** — Created `config.json` for all 10 workers. Schema: `{name, office, description, capabilities[], model}`.
+- **WP-03: OrgEngine Extension** — Extended `OrgEngine` to load `organization.json` alongside `offices.json`. Added schemas for roles, workers, collaboration pairs, and escalation triggers.
+- **WP-04: PromptAssembler** — New module (`src/prompt-assembler.ts`) that builds identity-aware prompts from SOUL.md + AGENTS.md + organizational context.
+- **WP-05: DispatchService Prompt Injection** — Modified `DispatchService` to inject assembled prompts into `subagent.run()` calls.
+- **WP-06: Classification Fixes** — Fixed `Dispatcher.classify()`: frontend keywords now route to `engineering` (was `product`), QA keywords now route to `engineering` (was `governance`). Updated `stageCapabilities` to match `organization.json` vocabulary.
+- **ADR-001**: Knowledge-Runtime Alignment architecture decision record. 8 decisions, 6 principles.
+- **Operational Validation**: 21 test scenarios across 8 categories. All pass. System verified against real data paths.
+
+#### Fixed
+
+- `WorkerConfigSchema.office` now allows `null` (accommodates dispatcher worker).
+- Dispatcher classification misrouting (frontend→product, QA→governance) corrected.
+- `stageCapabilities` strings aligned with `organization.json` vocabulary.
+
+#### Changed
+
+- `OrgEngine` constructor: `(configPath)` → `(configPath, orgPath?)`
+- `DispatchService` constructor: added optional `orgEngine` and `workersDir` parameters
+- `WorkerConfigSchema`: `office: z.string()` → `office: z.string().nullable()`
+
+#### Tests
+
+- 142 tests passing (13 new from milestone work)
+- 21 operational validation scenarios passing
+
+#### Known Limitations
+
+- `@openclaw/plugin-sdk` not published to npm — requires local stub for testing
+- 13 pre-existing test files in `src/__tests__/` have broken import paths (not caused by this milestone)
+- Multi-phase orchestration deferred (ADR-001 D6)
+- `policies.json` not loaded (no consumer)
+- SOUL.md voice inconsistency (deferred)
+
+---
+
+## [0.3.0] - 2026-07-03
+
+### Added
+
+- **WP-8: Organizational Execution** - Worker-aware delivery, org routing, pipeline planning
+  - WorkerEngine for worker discovery and capability matching
+  - OrgEngine for organizational structure and routing
+  - Pipeline planning for multi-stage task execution
+  - 141 tests passing (all work packages)
+
+- **WP-7: Workflow Intelligence** - Worker validation, task state tracking, reliability fixes
+  - TaskStateManager for ephemeral runtime task lifecycle tracking
+  - Worker validation in DispatchService before dispatch
+  - Session key collision prevention with random suffix
+  - Workboard timeout guard (30s RPC call timeout)
+  - Worker identity configs for all 9 workers
+
+- **WP-6: Workboard Integration** - Dual-path dispatch (workboard + fallback)
+  - WorkboardGateway for task card management
+  - Dual-path dispatch: workboard + direct execution
+  - 115 tests passing
+
+- **WP-5: Production Hardening** - DispatchService consolidation, input validation
+  - Consolidated triplicated dispatch logic into single DispatchService
+  - Input validation for all entry points
+  - 92 tests passing
+
+- **WP-4: Operator Interface** - CLI commands, agent tools, gateway RPC
+  - CLI commands for dispatch and management
+  - Agent tools for worker interaction
+  - Gateway RPC interface
+  - 43 tests passing
+
+- **WP-3: Multi-Worker Orchestration** - BE → QA handoff, self-healing rework loop
+  - Backend Engineer → QA Engineer handoff
+  - Self-healing rework loop (FAIL → Dispatcher → BE → QA PASS)
+  - 12/12 verification criteria passing
+
+- **WP-2: Single Worker Orchestration** - Dispatcher → Backend Engineer delegation
+  - Dispatcher orchestrates workers end-to-end
+  - Vertical slice test (8/8 criteria passing)
+
+- **WP-1: Foundation** - OpenClaw gateway, 9Router model router, dispatcher agent, 9 worker workspaces
+  - 10 agents registered in OpenClaw
+  - 9Router integration with 3 model profiles (Opus, Sonnet, Haiku)
+  - Dispatcher configured to orchestrate all 9 workers
+  - All workspace files created (AGENTS.md, SOUL.md)
+
+### Changed
+
+- **Repository Migration** - Standalone repository structure
+  - Migrated from `/home/tvd/office` to `/home/tvd/ai-engineering-company`
+  - Updated package.json: removed `workspace:*` dependency, added proper version constraints
+  - Expanded openclaw.plugin.json with compatibility and build information
+  - Comprehensive documentation archive (133 markdown files)
+
+---
+
+## [0.2.0] - 2026-06-30
+
+### Added
+
+- **Gate 1: Architecture** - Architecture design and validation
+- **Gate 2: Design** - Design review and approval
+- **Integration Contract** - 9Router integration determined
+- **Runtime Model Selection** - Behavior verified via source code analysis
+
+---
+
+## [0.1.0] - 2026-06-29
+
+### Added
+
+- **Initial Project Setup** - Repository structure and configuration
+- **Plugin Manifest** - openclaw.plugin.json definition
+- **Build Configuration** - package.json, tsconfig.json
+- **Documentation Structure** - docs/ directory organization
+
+---
+
+## Work Package Summary
+
+| WP | Name | Version | Status | Tests | Date |
+|----|------|---------|--------|-------|------|
+| WP-1 | Foundation | 0.3.0 | ✅ COMPLETE | 7 | 2026-06-30 |
+| WP-2 | Single Worker Orchestration | 0.3.0 | ✅ COMPLETE | 8/8 | 2026-07-01 |
+| WP-3 | Multi-Worker Orchestration | 0.3.0 | ✅ COMPLETE | 12/12 | 2026-07-02 |
+| WP-4 | Operator Interface | 0.3.0 | ✅ COMPLETE | 43 | 2026-07-02 |
+| WP-5 | Production Hardening | 0.3.0 | ✅ COMPLETE | 92 | 2026-07-03 |
+| WP-6 | Workboard Integration | 0.3.0 | ✅ COMPLETE | 115 | 2026-07-03 |
+| WP-7 | Workflow Intelligence | 0.3.0 | ✅ COMPLETE | 129 | 2026-07-03 |
+| WP-8 | Organizational Execution | 0.3.0 | ✅ COMPLETE | 141 | 2026-07-03 |
+| WP-9 | Slash Command & UX | 1.0.1 | ✅ CLOSED | 101 (7 suites) | 2026-07-04 |
+| WP-10 | Pipeline Execution | 1.0.1 | ✅ CLOSED | 101 (7 suites) | 2026-07-04 |
+| WP-11 | Human-in-the-Loop Approval | 1.1.0 | ✅ CLOSED | 195 (17 suites) | 2026-07-04 |
+| WP-12 | Production Validation | 1.2.0 | ✅ CLOSED | 195 (17 suites) | 2026-07-04 |
+| WP-13 | Event-driven DecisionQueue | 1.3.0 | ✅ CLOSED | 199 (17 suites) | 2026-07-04 |
+| WP-14 | Gateway RPC | 1.4.0 | ✅ CLOSED | 217 | 2026-07-04 |
+| WP-15 | DecisionQueue Persistence | 1.5.0 | ✅ CLOSED | 228 | 2026-07-04 |
+| WP-16 | Audit Logging | 1.6.0 | ✅ CLOSED | 236 | 2026-07-04 |
+| WP-17 | Technical Debt Resolution | 1.7.0 | ✅ CLOSED | 241 | 2026-07-04 |
+| WP-18 | Runtime Recovery | 1.8.0 | ✅ CLOSED | 241 | 2026-07-04 |
+| WP-19 | Multi-user Approval | 1.9.0 | ✅ CLOSED | 254 | 2026-07-04 |
+| WP-20 | Pipeline Checkpoint | 1.10.0 | ✅ CLOSED | 241 | 2026-07-04 |
+| WP-21 | Queue Backend Abstraction | 1.11.0 | ✅ CLOSED | 315 | 2026-07-04 |
+| WP-22 | Pipeline Resume | 1.12.0 | ✅ CLOSED | 320 | 2026-07-04 |
+| WP-23 | OpenClaw Identity Integration | 1.13.0 | ✅ CLOSED | 322 | 2026-07-04 |
+| WP-24 | Distributed Foundation | 1.14.0 | ✅ CLOSED | 351 | 2026-07-05 |
+| WP-25 | Pipeline Task State & Error Propagation | 1.15.0 | ✅ CLOSED | 351 | 2026-07-05 |
+
+## Documentation
+
+- **PROJECT-ARCHIVE.md** - Complete project archive and operational handover (1748 lines)
+- **docs/roadmap/** - Implementation roadmap, milestones, completion reports
+- **docs/architecture/** - System architecture and principles
+- **docs/ai-resource/** - AI resource management and routing