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-0002 Memory Slice)

Two implementation slices have been delivered:

- **CYA-WP-0001 (Console-Native MVP)**: Core CLI, context collection, rule-based safety with mandatory confirmation, LLMAdapter seam, and thin memory ports.
- **CYA-WP-0002 (Memory Integration)**: Real user-controlled, persisting memory implementation behind the explicit ports, wired into the orchestrator and `--explain-context`, memory signals integrated into safety, dedicated tests, and documentation.

Core capabilities now include:
- Natural language request handling via a clean Typer CLI.
- Bounded, transparent, non-recursive local context collection.
- Genuine rule-based risk classification (now memory-aware) with mandatory terminal confirmation.
- Stable `LLMAdapter` Protocol boundary.
- Real, user-controlled memory for preferences and workflow patterns (scoped JSON backing under `~/.config/cya/memory/`, fully inspectable and user-editable).
- Memory surfaced in explanations and fed into safety decisions.
- A small orchestrator coordinating the pipeline.

All LLM interaction flows through the documented adapter seam. Memory flows through explicit ports. No production path bypasses these 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).
- Packaging, distribution, or multi-platform installers beyond basic editable install.
- 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 | Explicit ports with real (local JSON) implementation (T02); long-term target is deeper profile-driven integration |
| State Hub     | Work tracking, decisions, coordination  | HTTP REST (non-runtime)           |

## MVP Scope (CYA-WP-0001)

What was explicitly in scope for the first slice:

- A functional `cya` CLI that accepts natural language requests.
- Safe, bounded context collection with full transparency (`--explain-context`).
- Rule-based safety classification as the primary mechanism, with mandatory confirmation.
- A clean, documented adapter boundary for future real LLM backends.
- Real user-controlled memory implementation (scoped, persisting, explainable) behind the explicit ports, with a clean seam for future deeper `phase-memory` integration.
- Basic orchestrator that ties the pieces together.
- Test coverage focused on safety invariants and context rules.
- Clear public boundaries and extension points.

## 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 as the first real backing; deeper integration is planned future work).
- Real `llm-connect` client (only the contract + fake exists).
- Deep git/repository understanding beyond basic status + log + user-declared memory.
- Automatic command execution (even "safe" suggestions).
- Structured editing / patch generation.
- Rich multi-turn conversational state (one-shot + lightweight scoped memory only).
- Cost tracking, token budgeting, or usage dashboards.
- Team/shared memory or collaboration features.
- Plugin system or domain-specific extensions.

## Extension Points (Registered)

- `cya/llm/adapter.py` — `LLMAdapter` Protocol (the primary seam).
- `cya/memory/__init__.py` — the four explicit ports with real (persisting, user-controlled) implementation behind them.
- `cya/safety/risk.py` — the `_RULES` table and `classify()` function.
- `cya/context/collector.py` — collection functions and ignore policy.
- `cya/orchestrator.py` — the main coordination entry point.

## Success Criteria (Current Slice)

A new user can:
- Clone the repo, run `pip install -e .`, and successfully use `cya` for 2–3 realistic tasks after reading only the README.
- Understand exactly what context is being sent via `--explain-context`.
- Trust that dangerous actions will never execute without explicit confirmation.
- See a clear path for how real `llm-connect` and `phase-memory` will plug in later.

Sibling project owners can read the workplan + boundary documentation and know precisely where their packages integrate.

---

**This SCOPE document reflects the state after CYA-WP-0001 (MVP) + CYA-WP-0002 (Memory Integration).**

It is intentionally narrower than the long-term vision in INTENT.md and MemoryVision.md, but now includes a real first slice of user-controlled memory as delivered by 0002.

See `workplans/CYA-WP-0002-memory-integration-roadmap.md` and `MemoryVision.md` for the intended direction of deeper `phase-memory` integration.