diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..b591868 --- /dev/null +++ b/.claude/rules/agents.md @@ -0,0 +1,32 @@ +## Agent entry points + +| Runtime | Canonical instructions | +| --- | --- | +| **Grok / Codex** (shell) | `AGENTS.md` at repo root | +| **Claude Code** | This file tree via `CLAUDE.md` | + +`AGENTS.md` and `.claude/rules/` are kept in sync for repo-specific content. +Fleet-wide credential routing is mirrored in `credential-routing.md` and the +matching section of `AGENTS.md` — re-sync from `~/ops-warden/wiki/CredentialRouting.md` +when the catalog changes. + +## Kaizen Agents + +Specialized agent personas available on demand via the state-hub MCP. + +**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category +**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them + +Common agents: + +| Agent | Category | When to use | +|-------|----------|-------------| +| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature | +| `code-refactoring` | quality | Code quality analysis and safe refactoring | +| `test-maintenance` | testing | Diagnose and fix failing tests | +| `requirements-engineering` | process | Prevent interface/mock mismatches upfront | +| `keepaTodofile` | process | Maintain TODO.md during work | +| `project-management` | process | Track status, determine next steps | +| `datamodel-optimization` | quality | Optimize dataclasses and data structures | + +All 17 agents: call `list_kaizen_agents()` for the full list. \ No newline at end of file diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 0000000..ae6c786 --- /dev/null +++ b/.claude/rules/architecture.md @@ -0,0 +1,23 @@ +## Architecture + +**Request pipeline** (`src/cya/orchestrator.py`): +1. Collect local context (`context/collector.py`) +2. Recall memory via phase-memory ports (`memory/__init__.py`) +3. Classify risk (`safety/risk.py`) — rule-based; memory signals add caution only +4. Call LLM via `LLMAdapter` Protocol (`llm/adapter.py`) — FakeLLMAdapter today +5. Render explainable response (Rich) + +**Memory (Profile 0 + Profile 1 spike):** +- User-controlled local JSON behind explicit ports (`remember`, `recall`, `forget`, `export`) +- Kinds: `preference`, `retrospection`, `interaction_goal`, `reflection` +- Directory/project-bound activation via `activation_context` +- `cya retrospect` feeds higher-order memory; optional verbal lesson capture (Profile 1) + +**Boundaries:** See `repo-boundary.md`. No production path bypasses the adapter or memory ports. + +## Quick Reference + +- Memory contract: `MemoryVision.md` +- Activation/retrospection concept: `docs/cya-memory-activation-and-retrospection-concept.md` +- phase-memory feedback: `docs/phase-memory-optimization-suggestions.md` +- `~/state-hub/mcp_server/TOOLS.md` — MCP tool reference \ No newline at end of file diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md new file mode 100644 index 0000000..143fe7b --- /dev/null +++ b/.claude/rules/credential-routing.md @@ -0,0 +1,54 @@ +# Credential and access routing + +> Fleet template mirrored in `AGENTS.md` (Credential and access routing section). +> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes. + +**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** +for inference. Run this check **before** requesting secrets, API keys, SSH access, +login tokens, or database passwords — in any repo, not only `ops-warden`. + +ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every +other credential need belongs to another subsystem. **Do not** message +`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. + +### Lookup (do this first) + +```bash +warden route find "" --json +warden route show --json +``` + +Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). + +| Agent runtime | How to orient | +| --- | --- | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=can-you-assist` is for coordination, not secret vending | +| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | +| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | + +### Quick routing table + +Prefer `warden route find` for repo-specific needs. Common routes: + +| I need… | Owner | ops-warden executes? | +| --- | --- | --- | +| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | +| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | +| Login / OIDC / MFA | key-cape / Keycloak | No — route only | +| Authorization decision | flex-auth | No — route only | +| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | + +### Anti-patterns (do not do these) + +- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. +- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist +- Pasting secrets into Git, State Hub, workplans, logs, or chat + +### Other capabilities (reuse-surface) + +Non-credential capabilities are usually discovered through **reuse-surface** federation +(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in +every repo's agent instructions because it is high-frequency, high-risk, and easy to +get wrong. + +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` \ No newline at end of file diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md new file mode 100644 index 0000000..67fa109 --- /dev/null +++ b/.claude/rules/first-session.md @@ -0,0 +1,37 @@ +## First Session Protocol + +Triggered when `get_domain_summary("capabilities")` shows **no workstreams**. +The project is registered but work has not yet been structured. + +**Step 1 — Read, don't write** +- `INTENT.md`, `README.md`, `SCOPE.md`, `AGENTS.md`, `MemoryVision.md` +- Scan repo root: `src/cya/`, `workplans/`, `tests/` + +**Step 2 — Survey in-progress work** +Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. + +**Step 3 — Propose workstreams to Bernd** +Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to +INTENT/SCOPE. **Wait for approval before creating.** + +**Step 4 — Create workplan file first, then DB record (ADR-001)** +``` +workplans/CYA-WP-NNNN-.md ← write this first +``` +Then register in the hub: +``` +create_workstream(topic_id="64418556-3206-457a-ba29-6884b5b12cf3", title="...", owner="...", description="...") +create_task(workstream_id="", title="...", priority="high|medium|low") +``` + +**Step 5 — Record the setup** +``` +add_progress_event( + summary="First session: structured capabilities/can-you-assist into N workstreams, M tasks", + event_type="milestone", + topic_id="64418556-3206-457a-ba29-6884b5b12cf3", + detail={"workstreams": [...], "tasks_created": M} +) +``` + + \ No newline at end of file diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..db625e5 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,11 @@ +## Repo boundary + +This repo owns **can-you-assist** (`cya`) only. It does not own: + +- LLM provider access, API clients, or model hosting → `llm-connect` +- Durable memory storage, profile planners, graph/event stores, or lifecycle algorithms → `phase-memory` +- Global work tracking, decisions, or cross-repo coordination → State Hub / custodian +- Credential custody (API keys, DB passwords, OIDC) → OpenBao / key-cape / operator paths (route via `warden route`) +- SSH certificate issuance → `ops-warden` (`warden sign` only) + +`cya` integrates via stable seams (`LLMAdapter` Protocol, memory ports). State Hub is non-runtime. \ No newline at end of file diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..2b84645 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,7 @@ +**Purpose:** Console-native, backend-agnostic LLM assistant (`cya`) for practical local work from the shell, using user-controlled context, memory, and provider configuration. + +**Domain:** capabilities +**Repo slug:** can-you-assist +**Topic ID:** 64418556-3206-457a-ba29-6884b5b12cf3 +**Workplan prefix:** CYA-WP- +**Command name:** cya \ No newline at end of file diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..912cce1 --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,90 @@ +## Session Protocol + +State Hub: http://127.0.0.1:8000 (remote tunnel: http://127.0.0.1:18000) + +**Step 1 — Orient** + +Read the offline-safe brief first — it works without a live hub connection: +```bash +cat .custodian-brief.md +``` +Then call the MCP tool for richer cross-domain context when MCP tools are exposed: +``` +get_domain_summary("capabilities") +``` +If MCP tools are unavailable in the current agent session, use the REST API: +```bash +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \ + | python3 -m json.tool +``` +If the hub is offline: `cd ~/state-hub && make api` + +**Step 2 — Check inbox** +With MCP tools: +``` +get_messages(to_agent="can-you-assist", unread_only=True) +``` +Mark read with `mark_message_read(message_id)`. Reply or act on coordination +requests before proceeding. + +Without MCP tools: +```bash +curl -s "http://127.0.0.1:8000/messages/?to_agent=can-you-assist&unread_only=true" \ + | python3 -m json.tool +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +**Step 3 — Scan workplans** +```bash +ls workplans/ +``` +For each file with `status: ready`, `active`, or `blocked`, note pending +`todo`/`in_progress` tasks. + +**Step 4 — Present brief** + +1. **Active workstreams** for `capabilities` — title, task counts, blocking decisions +2. **Pending tasks** from `workplans/` + any `[repo:can-you-assist]` hub tasks +3. **Goal guidance** — if `goal_guidance` in summary: + - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* + - `alignment_warnings`: flag if active work is not aligned with current goal +4. **Suggested next action** — highest-priority open item +5. **SBOM status** — flag if `last_sbom_at` is unset for this repo + +If no workstreams: follow First Session Protocol (`first-session.md`). + +**During work:** +- Keep changes small and inspectable. +- Treat command execution safety as product behavior: explain destructive commands and require explicit confirmation before suggesting execution. +- Do not commit secrets, API keys, local transcripts, private notes, or hidden memory contents. +- Before requesting API keys, SSH access, login tokens, or database passwords, run `warden route find` / `warden route show` per `credential-routing.md`. +- `record_decision()` · `add_progress_event()` · `resolve_decision()` + +> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`) +> are First Session Protocol only. Work structure belongs in repo files (ADR-001). + +**Session close:** +With MCP tools: +``` +add_progress_event(summary="...", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", workstream_id="") +``` +Without MCP tools: +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{"topic_id":"64418556-3206-457a-ba29-6884b5b12cf3","workstream_id":"","event_type":"note","summary":"what changed","author":"codex"}' +``` +If workplan files were modified, ensure the local copy is up to date first: +```bash +git -C pull --ff-only +cd ~/state-hub && make fix-consistency REPO=can-you-assist +``` +For repos where implementation runs on a remote machine (e.g. CoulombCore), +use the combined target which pulls before fixing: +```bash +cd ~/state-hub && make fix-consistency-remote REPO=can-you-assist +``` +**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback +will sync the file to match DB. **C-16** (repo behind remote) blocks all writes +until you pull — intentional to prevent clobbering remote progress. \ No newline at end of file diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md new file mode 100644 index 0000000..9b08c87 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,38 @@ +## Stack + +- **Language:** Python 3.11+ +- **CLI:** Typer + Rich +- **Config:** TOML +- **Packaging:** setuptools + setuptools_scm (`src/` layout) +- **Tests:** pytest + +## Dev Commands + +```bash +# Recommended: install latest development code +make dev-install + +# Run tests +make test +# or: python3 -m pytest tests/ -q + +# Build distribution packages +make dist +make release-prep +make check-dist + +# Run the assistant +cya "your natural language request here" +cya --help +cya --explain-context "show me what context would be collected" +cya retrospect + +# Version / inspection +make version +git status --short +rg --files +``` + +Current memory baseline: **Profile 0** (local JSON + activation + retrospection). +Profile 1 verbal reflections shipped as a minimal spike (CYA-WP-0005); production +hardening tracked in CYA-WP-0006. \ No newline at end of file diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..ec39f03 --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,28 @@ +## Workplan Convention (ADR-001) + +File location: `workplans/CYA-WP-NNNN-.md` +ID prefix: `CYA-WP-` + +Work items originate as files in this repo **before** being registered in the hub. + +Canonical workplan/workstream frontmatter statuses are: +`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`. +Use `proposed` for a newly drafted plan, `ready` after review against current +repo state, and `finished` when implementation is complete. `stalled` and +`needs_review` are derived health labels, not stored statuses. + +Closed workplans may be moved to `workplans/archived/` with a completion-date +prefix: `YYMMDD-CYA-WP-NNNN-.md`. The frontmatter id remains +unchanged; the prefix is only for quick visual reference. + +Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: +`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids +`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed +directly. Promote anything requiring analysis, design, approval, dependencies, or +multiple planned phases into a normal workplan. + +Ecosystem todos from other agents arrive as `[repo:can-you-assist]` hub tasks — +visible at session start. Pick one up by creating the workplan file, then registering +the workstream. + + \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index dbc50ca..a3c83b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,6 +126,8 @@ During work: - Treat command execution safety as product behavior: explain destructive or broad filesystem commands and require explicit confirmation before suggesting execution. +- Before requesting API keys, SSH access, login tokens, or database passwords, + run `warden route find` / `warden route show` per **Credential and access routing**. - Do not commit secrets, API keys, local transcripts, private notes, or hidden memory contents. - Preserve user-controlled memory as a design principle. Prefer explicit, @@ -207,7 +209,68 @@ Current primary entry point: `cya` (after editable install). Relevant workplans: - `workplans/CYA-WP-0002-memory-integration-roadmap.md` - `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md` -- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md` (current) +- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md` +- `workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md` +- `workplans/CYA-WP-0006-profile-1-production-hardening.md` (proposed — next slice) + +--- + +## Credential and access routing + +> Fleet template mirrored in `.claude/rules/credential-routing.md` for Claude Code. +> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes. + +**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** +for inference. Run this check **before** requesting secrets, API keys, SSH access, +login tokens, or database passwords — in any repo, not only `ops-warden`. + +ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every +other credential need belongs to another subsystem. **Do not** message +`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. + +### Lookup (do this first) + +```bash +warden route find "" --json +warden route show --json +``` + +Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). + +| Agent runtime | How to orient | +| --- | --- | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=can-you-assist` is for coordination, not secret vending | +| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | +| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | + +### Quick routing table + +Prefer `warden route find` for repo-specific needs. Common routes: + +| I need… | Owner | ops-warden executes? | +| --- | --- | --- | +| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | +| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | +| Login / OIDC / MFA | key-cape / Keycloak | No — route only | +| Authorization decision | flex-auth | No — route only | +| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | + +### Anti-patterns (do not do these) + +- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. +- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist +- Pasting secrets into Git, State Hub, workplans, logs, or chat + +### Other capabilities (reuse-surface) + +Non-credential capabilities are usually discovered through **reuse-surface** federation +(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in +every repo's agent instructions because it is high-frequency, high-risk, and easy to +get wrong. + +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` + +--- ## Workplan Convention diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6e5d2c0 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,12 @@ +# can-you-assist — Claude Code Instructions + +@SCOPE.md +@.claude/rules/repo-identity.md +@.claude/rules/session-protocol.md +@.claude/rules/first-session.md +@.claude/rules/workplan-convention.md +@.claude/rules/stack-and-commands.md +@.claude/rules/architecture.md +@.claude/rules/repo-boundary.md +@.claude/rules/credential-routing.md +@.claude/rules/agents.md \ No newline at end of file diff --git a/workplans/CYA-WP-0002-memory-integration-roadmap.md b/workplans/CYA-WP-0002-memory-integration-roadmap.md index d66edfa..ba3cf1b 100644 --- a/workplans/CYA-WP-0002-memory-integration-roadmap.md +++ b/workplans/CYA-WP-0002-memory-integration-roadmap.md @@ -137,10 +137,11 @@ completed: "2026-05-26" ```task id: CYA-WP-0002-T05 -status: progress +status: done priority: high state_hub_task_id: "d30f159c-3459-4c7b-ba31-990a73deaffb" started: "2026-05-26 final ralph push" +completed: "2026-05-28" ``` - Expand the test suite (building on T07) with memory-specific tests (in-memory fake phase-memory adapter, profile scenarios, error cases). diff --git a/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md b/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md index 6454806..eacd62f 100644 --- a/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md +++ b/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md @@ -254,7 +254,9 @@ When complete: --- -**Status note**: This workplan is created in `proposed` state. It captures a focused, high-leverage planning and feedback slice. Implementation of the profiles (beyond the baseline documentation and optional Profile 1 spike) should be activated only after review and operator go-ahead, following the ralph-workplan discipline used for 0001–0004. +**Status note**: Completed 2026-05-28. Profile 0 baseline, Profiles 1–3 definitions, phase-memory +feedback artifact, and minimal Profile 1 spike are delivered. Production hardening for Profile 1 +is tracked in `workplans/CYA-WP-0006-profile-1-production-hardening.md`. **References** (non-exhaustive): - Research: `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` diff --git a/workplans/CYA-WP-0006-profile-1-production-hardening.md b/workplans/CYA-WP-0006-profile-1-production-hardening.md new file mode 100644 index 0000000..eae306d --- /dev/null +++ b/workplans/CYA-WP-0006-profile-1-production-hardening.md @@ -0,0 +1,199 @@ +--- +id: CYA-WP-0006 +type: workplan +title: "Profile 1 Production Hardening: Reflection UX, Compaction, and Surfacing" +domain: capabilities +repo: can-you-assist +status: proposed +owner: grok +topic_slug: foerster-capabilities +created: "2026-06-19" +updated: "2026-06-19" +--- + +# 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. + +## 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: todo +priority: high +``` + +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). + +### T02 — Improve `cya retrospect` reflection capture UX + +```task +id: CYA-WP-0006-T02 +status: todo +priority: high +``` + +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. + +### T03 — Reflection review and lightweight compaction + +```task +id: CYA-WP-0006-T03 +status: todo +priority: medium +``` + +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. + +### T04 — Strengthen surfacing in responses and `--explain-context` + +```task +id: CYA-WP-0006-T04 +status: todo +priority: high +``` + +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. + +### T05 — Tests, observability, and safety regression coverage + +```task +id: CYA-WP-0006-T05 +status: todo +priority: high +``` + +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. + +### T06 — Documentation updates + +```task +id: CYA-WP-0006-T06 +status: todo +priority: medium +``` + +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. + +### T07 — Register, sync, and handoff + +```task +id: CYA-WP-0006-T07 +status: todo +priority: medium +``` + +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. + +--- + +**Status note:** Created `proposed` on 2026-06-19 after CYA-WP-0005 completion and gap +analysis recommendations. Activate to `ready` after operator review; move to `active` when +implementation begins (ralph-workplan or direct session). \ No newline at end of file