can-you-assist/workplans/CYA-WP-0006-profile-1-production-hardening.md

---
id: CYA-WP-0006
type: workplan
title: "Profile 1 Production Hardening: Reflection UX, Compaction, and Surfacing"
domain: agents
repo: can-you-assist
status: finished
owner: grok
topic_slug: foerster-capabilities
created: "2026-06-19"
updated: "2026-06-22"
state_hub_workstream_id: "f62c6908-dec0-442c-83d2-e34f0e87c1e7"
---

# CYA-WP-0006: Profile 1 Production Hardening

## Goal

Move the **Profile 1** (Reflexion-style verbal reflections) spike from CYA-WP-0005-T05
from "minimal but working" to **production-quality** behavior that users can rely on daily:

- Clearer capture UX inside `cya retrospect`
- Lightweight reflection management (review, edit path, basic compaction)
- Stronger surfacing in normal responses and `--explain-context`
- Expanded tests and observability

Preserve all Profile 0 / safety invariants: user-controlled inspectable memory, full
provenance, memory signals add caution only (never downgrade risk or bypass confirmation).

## Background & References

- **Profile 1 spike (done):** `remember_reflection()`, `KIND_REFLECTION`, optional capture
  step in `run_retrospection()`, preferential recall by kind, basic output surfacing.
- **Gap analysis:** `history/2026-05-28-CYA-Intent-Scope-Gap-Analysis-Post-0005.md` —
  recommends production-hardening Profile 1 as the highest-leverage next deepening step.
- **Profile definitions:** MemoryVision.md — Profile 1 section and Capability Matrix.
- **Safety contract:** `src/cya/safety/risk.py` + CYA-WP-0002-T04 invariants.
- **Gap checklist (T01):** `docs/CYA-WP-0006-profile-1-gap-checklist.md`

## Non-Goals (for this slice)

- Profile 2 (hierarchical synthesis) or Profile 3 (procedural evolution) implementation.
- Real `llm-connect` client wiring (separate future slice).
- Deep `phase-memory` graph/planner integration (feedback doc exists; wiring is later).
- Automatic background reflection generation without explicit user trigger.
- PyPI publishing or CI automation (registered debt from CYA-WP-0004).

## Task Breakdown

### T01 — Audit Profile 1 spike gaps vs MemoryVision acceptance

```task
id: CYA-WP-0006-T01
status: done
priority: high
state_hub_task_id: "ec8cc24d-80ca-4a51-b98c-87d0cfc9a110"
```

Document the delta between shipped spike behavior and MemoryVision Profile 1 acceptance
criteria: capture UX, activation surfacing, compaction, explainability, safety integration.
Produce a short checklist in the workplan or `docs/` that gates T02–T05.

**Acceptance criteria:**
- Gap checklist exists with prioritized items mapped to tasks T02–T05.
- No code changes required unless a blocking bug is found (file separately as ADHOC if so).

**Done:** `docs/CYA-WP-0006-profile-1-gap-checklist.md`

### T02 — Improve `cya retrospect` reflection capture UX

```task
id: CYA-WP-0006-T02
status: done
priority: high
state_hub_task_id: "c7f381d4-d362-4183-a7bd-d3ceea7e997d"
```

Enhance the optional verbal-lesson step in `run_retrospection()`:

- Guided prompts (what went well / what to remember / what to avoid)
- Preview before save; allow skip without storing empty records
- Store structured metadata (session date, scope) in provenance

**Acceptance criteria:**
- Users can capture 1–3 concise lessons with clear prompts and confirmation.
- Skipping leaves no orphan/empty reflection records.
- Existing retrospection kinds and goals flow unchanged.

**Done:** `_capture_reflection_lessons()` in `orchestrator.py`; helpers in `memory/reflections.py`.

### T03 — Reflection review and lightweight compaction

```task
id: CYA-WP-0006-T03
status: done
priority: medium
state_hub_task_id: "078d6f17-6d56-42ec-85c9-140c41d7e83f"
```

Add user-visible reflection management without hiding state:

- `export_memory(..., kinds=["reflection"])` surfaced via CLI helper or documented path
- Simple compaction: detect near-duplicate reflections in the same scope (string similarity
  or normalized key collision) and offer merge/replace in retrospect or a small subcommand
- All compaction is explicit — no silent deletion

**Acceptance criteria:**
- User can list/export reflections for a scope.
- Duplicate detection works on a small fixture set; merge/replace is opt-in.
- Compaction never bypasses safety or provenance requirements.

**Done:** `cya memory reflections` CLI; `_offer_reflection_compaction()` in retrospect; `compact_reflections()` / `find_duplicate_reflection_groups()`.

### T04 — Strengthen surfacing in responses and `--explain-context`

```task
id: CYA-WP-0006-T04
status: done
priority: high
state_hub_task_id: "b1f7a333-bf9a-478c-993b-e421524ced3a"
```

Improve how activated reflections appear in `handle_request()` and context explanation:

- Show count + truncated lesson text in `--explain-context` with provenance
- Normal responses include a concise "reflections influenced this" line when relevant
- Cap token/line budget to avoid wall-of-text

**Acceptance criteria:**
- Roundtrip test: stored reflection → recall → visible in explain output.
- Output remains readable for 0, 1, and 5+ reflections.

**Done:** `format_reflection_surfacing()`; recall prioritization for `KIND_REFLECTION`.

### T05 — Tests, observability, and safety regression coverage

```task
id: CYA-WP-0006-T05
status: done
priority: high
state_hub_task_id: "b42c8fa1-6ab7-4b75-bdd5-43006e2d0a9c"
```

Expand `tests/test_memory.py` and orchestrator tests for:

- New capture UX paths (prompt/skip/preview)
- Compaction opt-in behavior
- Surfacing in explain-context
- Safety invariant: reflections cannot downgrade destructive-command confirmation

Add basic observability in `export_memory` (reflection counts by scope).

**Acceptance criteria:**
- `make test` / `python3 -m pytest tests/ -q` passes cleanly.
- At least one test per new behavior path from T02–T04.

**Done:** 9 new tests in `test_memory.py`; `tests/test_orchestrator.py` added.

### T06 — Documentation updates

```task
id: CYA-WP-0006-T06
status: done
priority: medium
state_hub_task_id: "18498a09-1d1c-424b-bf13-6952fabd34d3"
```

Update README.md (retrospect / Profile 1 section), MemoryVision.md status note, and
SCOPE.md if delivered scope changes materially.

**Acceptance criteria:**
- README documents the hardened Profile 1 flow with an example session.
- MemoryVision notes Profile 1 as "production" (not "spike") when T02–T05 complete.

**Done:** README, MemoryVision, SCOPE updated.

### T07 — Register, sync, and handoff

```task
id: CYA-WP-0006-T07
status: done
priority: medium
state_hub_task_id: "a9c2627f-7ed8-45a9-b1ee-7ba64ebbcd09"
```

Register workstream in State Hub via `make fix-consistency REPO=can-you-assist`,
log progress event, set workplan to `ready` after review or `active` when implementation
starts.

**Acceptance criteria:**
- `state_hub_workstream_id` and task ids written by fix-consistency.
- `.custodian-brief.md` regenerated with CYA-WP-0006 visible.

## Dependencies & Cross-Repo Coordination

- **phase-memory:** Optional future compaction planner hooks — not required for this slice.
  See `docs/phase-memory-optimization-suggestions.md` for long-term asks.
- **llm-connect:** Not required (reflections are user-authored text in this slice).

## Debt & Future Work (Registered)

- Profile 2 synthesis spikes (user-triggered, dry-run first).
- Real `llm-connect` adapter implementation slice.
- CI gate for `make test` + `make check-dist` (from CYA-WP-0004 debt).
- Profile selection UX (`cya memory profile ...`).

## Success Criteria

When complete:

- Profile 1 is demonstrably production-usable: capture, review, activation, and surfacing
  are polished and tested.
- Safety and explainability invariants from Profile 0 remain intact.
- Users reading README + MemoryVision understand Profile 1 as shipped capability, not a spike.

**Completed 2026-06-22.** All tasks done; 36 tests pass.