can-you-assist/SCOPE.md

# Scope: can-you-assist

## Purpose

`can-you-assist` provides the `cya` command — a console-native, backend-agnostic LLM assistant for practical local work.

It allows users to express intent in natural language from the terminal and receive safe, explainable, context-aware assistance while keeping memory, history, preferences, and adaptation under explicit user control.

## Current Status (Post CYA-WP-0004 Packaging & Distribution Slice)

Four implementation slices have been delivered:

- **CYA-WP-0001 (Console-Native MVP)**: Core CLI, bounded context collection, rule-based safety with mandatory confirmation, LLMAdapter Protocol seam, basic orchestrator.
- **CYA-WP-0002 (Memory Integration)**: Real user-controlled, persisting memory (scoped JSON) behind explicit ports, wired into context and safety.
- **CYA-WP-0003 (Contextual Activation & Retrospection)**: Directory/project-bound automatic memory activation, `cya retrospect` guided reflection sessions, retrospection outcomes feeding future behavior (continuous user-driven optimization loop).
- **Profile 0 baseline (post-0003, formalized in CYA-WP-0005 T02)**: The current shipped memory implementation (local JSON + kinds + activation_context + provenance + retrospection helper) is now explicitly documented as **Profile 0** — the stable, high-quality foundation for future self-improving profiles 1–3. See MemoryVision.md for the full baseline description.
- **CYA-WP-0005 (Agentic Memory Profiles + first self-improvement capability)**: Complete profile model (Profile 0 baseline + detailed definitions + integration plans + Capability Matrix for Profiles 1–3) plus a minimal but fully working **Profile 1** (Reflexion-style verbal reflections/lessons) spike: `remember_reflection()` + `KIND_REFLECTION`, optional "capture verbal lesson" step inside `cya retrospect`, preferential activation when reflections are present, and surfacing in responses / `--explain-context`. The sister-repo optimization suggestions document for phase-memory was also finalized. See the workplan, MemoryVision.md, and `docs/phase-memory-optimization-suggestions.md`.
- **CYA-WP-0004 (Dev-Head Install & Release Packaging)**: Reliable installation from development head (`make dev-install`, direct `git+` installs), dynamic versioning via `setuptools_scm`, clean distribution package building (`python -m build` + verification), lightweight release process, and supporting documentation/Makefile.

Core capabilities now include:
- Natural language request handling via clean Typer CLI.
- Bounded, transparent local context collection.
- Genuine rule-based (memory-aware) risk classification with mandatory confirmation.
- Stable `LLMAdapter` Protocol.
- Real, user-controlled, contextually activated memory (Profile 0: directory/project scoped local JSON with kinds, activation_context, provenance, and retrospection outcomes as higher-order memory).
- Automatic memory activation based on working directory/git root.
- `cya retrospect` for structured reflection and goal setting, now with optional verbal lesson capture (first delivered Profile 1 self-improvement behavior).
- Full developer workflow: dev-head install, testing, building distribution packages, and a documented release process.
- Transparent, inspectable behavior via `--explain-context`.

All LLM interaction flows through the documented adapter seam. Memory flows through explicit ports. Packaging and distribution are now first-class concerns with a clear path forward. No production path bypasses the defined boundaries.

## Owns

- The `cya` command-line user experience and argument parsing.
- Intent framing and high-level task classification for console work.
- Local context collection (current directory, git state, selected files, stdin, minimal environment facts).
- Safety layer: rule-based risk assessment + mandatory explicit confirmation flow.
- Orchestration of the request → context → safety → LLM adapter → response pipeline.
- The stable `LLMAdapter` Protocol and the contract for how `cya` talks to LLM backends.
- Explicit, now real (persisting) integration with user-controlled memory via `phase-memory` ports.
- Transparent, inspectable behavior (especially via `--explain-context`).
- User-facing documentation, examples, and safety guarantees for the CLI tool.

## Does Not Own

- Any specific LLM provider, API client, or model hosting (belongs to `llm-connect`).
- Durable memory storage, preference models, history semantics, or adaptation algorithms (belongs to `phase-memory`).
- Global work tracking, decisions, or cross-repo coordination (belongs to State Hub / custodian).
- Autonomous or background execution of commands without explicit user confirmation.
- Deep repository indexing, embeddings, or large-scale content analysis (explicit non-goal of the first slice).
- Voice, speech, phone-bridge, or non-terminal interfaces (future work).
- Production PyPI publishing and automated release CI (documented process and local tooling exist; actual publication is future work).
- Long-lived conversational REPL or session state (one-shot + very lightweight session only).

## Integrates With

| Project       | Responsibility                          | Integration Style                  |
|---------------|-----------------------------------------|------------------------------------|
| `llm-connect` | Provider access, config, token counting, structured responses | Stable `LLMAdapter` Protocol      |
| `phase-memory`| User-controlled memory, preferences, history, profiles, and activation planning | Explicit ports with real (local JSON + contextual activation + retrospection) implementation; long-term target is deeper profile-driven integration |
| State Hub     | Work tracking, decisions, coordination  | HTTP REST (non-runtime)           |

## Current Delivered Scope (Post CYA-WP-0005 T05)

Significant slices have been delivered beyond the original MVP (most recently the full profile model and first self-improving capability from CYA-WP-0005):

- Full console-native CLI with rich output.
- Context-aware, directory/project-bound memory activation.
- User-driven retrospection and continuous optimization loops (`cya retrospect`).
- Real, inspectable, user-controlled memory with strong explainability and safety integration.
- Complete developer workflow: installation from dev head, testing, building distribution packages, and a documented release process.
- Packaging and distribution now treated as first-class concerns (with registered future work).

See the individual workplans for detailed scope per slice.

## Explicitly Out of Scope (Current and Near-Term)

- Full deep integration with the complete `phase-memory` profile/planner/graph system (current implementation uses a deliberate, user-visible local JSON store with contextual activation; deeper integration is planned future work per MemoryVision.md).
- Real `llm-connect` client implementation (only the stable `LLMAdapter` Protocol contract + FakeLLMAdapter exists).
- Deep semantic repository understanding or large-scale content analysis.
- Automatic command execution (even "safe" suggestions) — explicit user confirmation remains mandatory for anything non-safe.
- Rich multi-turn conversational state beyond lightweight scoped memory + retrospection.
- Cost tracking, token budgeting, or usage dashboards.
- Team/shared memory or collaboration features.
- Plugin system or domain-specific extensions.
- Production PyPI publishing and fully automated release CI (a lightweight documented local process exists; automation is future work).

## Extension Points (Registered)

- `cya/llm/adapter.py` — `LLMAdapter` Protocol (the primary seam).
- `cya/memory/__init__.py` — the explicit ports (with real implementation, contextual activation, and retrospection support).
- `cya/safety/risk.py` — the `_RULES` table and `classify()` function (memory-aware).
- `cya/context/collector.py` — collection functions and ignore policy.
- `cya/orchestrator.py` — the main coordination entry point.
- Packaging & distribution: `Makefile`, `pyproject.toml`, `docs/release-process.md`, and `MANIFEST.in` (first-class concern with registered future work).

## Success Criteria (Current State)

A new user or contributor can:
- Install the latest development code easily (`make dev-install` or direct git+) and use `cya` for realistic tasks after reading the README.
- Understand exactly what context and memory influenced a response via `--explain-context`.
- Trust that dangerous actions will never execute without explicit confirmation.
- Use `cya retrospect` to reflect on usage and set goals that influence future behavior.
- Build and verify distribution packages locally.
- See a clear path for how real `llm-connect`, deeper `phase-memory`, and future PyPI releases will integrate.

Sibling project owners (llm-connect, phase-memory, State Hub) can read the workplans + boundary documentation and know precisely where their packages integrate.

---

**This SCOPE document reflects the state after CYA-WP-0004 (Dev-Head Install & Release Packaging).**

It remains intentionally narrower than the long-term vision in INTENT.md and MemoryVision.md, but now incorporates significant advances in contextual memory activation, user-driven retrospection/optimization loops, and proper packaging & distribution capabilities.

See the individual workplans (especially CYA-WP-0003 and CYA-WP-0004) and `MemoryVision.md` for the intended direction of deeper `phase-memory` integration and future evolution.