# v8.11 ACON-Inspired Compression Guideline Optimizer Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Implement an ACON-style closed-loop optimizer that updates compression guidelines from observed action outcomes and recall quality telemetry.

**Architecture:** Build a deterministic nightly optimizer job over `memory-actions.jsonl` + recall traces, with optional LLM refinement pass behind a strict budget/time gate. Persist guideline versions and apply them read-only in runtime paths.

**Tech Stack:** TypeScript, `src/orchestrator.ts`, `src/storage.ts`, `src/recall-state.ts`, existing telemetry artifacts, node:test.

---

## Task 1: Define optimizer state model + versioning

**Files:**
- Modify: `src/types.ts`
- Modify: `src/storage.ts`
- Test: `tests/storage-policy-state.test.ts`
- Docs: `docs/config-reference.md`

**Steps:**
1. Add typed schema for guideline versions and optimizer metadata (source window, event counts, updatedAt).
2. Add storage read/write APIs with strict parse + fail-open fallback.
3. Add tests for round-trip, malformed state, and empty-input behavior.

## Task 2: Implement deterministic optimizer engine

**Files:**
- Create: `src/compression-optimizer.ts`
- Modify: `src/orchestrator.ts`
- Test: `tests/compression-optimizer.test.ts`

**Steps:**
1. Aggregate telemetry by action, outcome, and downstream recall quality markers.
2. Compute conservative rule updates (bounded deltas, no hard removals on sparse data).
3. Emit next guideline candidate + confidence notes.
4. Add deterministic snapshot tests.

## Task 3: Add optional semantic refinement pass

**Files:**
- Modify: `src/compression-optimizer.ts`
- Modify: `src/config.ts`
- Modify: `src/types.ts`
- Test: `tests/compression-optimizer-semantic.test.ts`
- Docs: `docs/setup-config-tuning.md`

**Steps:**
1. Add flags/timeouts for semantic refinement.
2. Run refinement only after deterministic baseline completes.
3. Enforce hard timeout + fail-open fallback to deterministic output.
4. Add tests for timeout/error fallback.

## Task 4: Add optimizer tool + cron-safe entry point

**Files:**
- Modify: `src/tools.ts`
- Modify: `src/orchestrator.ts`
- Test: `tests/tools-compression-optimize.test.ts`
- Docs: `docs/operations.md`

**Steps:**
1. Add `compression_guidelines_optimize` tool with dry-run mode.
2. Add explicit summary output: old version, new version, changed rules.
3. Ensure cron usage is isolated and non-blocking.

## Task 5: Runtime integration and guardrails

**Files:**
- Modify: `src/orchestrator.ts`
- Test: `tests/recall-compression-guideline-application.test.ts`

**Steps:**
1. Apply latest active guidelines during compression-related recall assembly only.
2. Keep zero-change path byte-equivalent when optimizer disabled.
3. Add regression tests for disabled, enabled, and malformed-guideline states.

