can-you-assist/README.md

# cya — console-native assistant for local work

`cya` lets you express intent in natural language from your terminal and receive
safe, explainable, context-aware help.

It is the CLI surface for the capabilities domain. It owns orchestration,
the user experience, and the safety layer. It talks to `llm-connect` only
through a stable adapter boundary and keeps all memory under explicit
user-controlled ports (implemented by `phase-memory`).

## Status

This is the first narrow MVP slice (CYA-WP-0001). The tool is already
usable after `pip install -e .`:

- `cya "your request in plain English"`
- `cya --explain-context "..."` — shows exactly what local context would be sent
- Automatic rule-based risk classification with mandatory confirmation for anything destructive, privileged, mass-edit, or network-affecting
- All LLM interaction flows through a documented `LLMAdapter` seam (currently a deterministic fake; ready for real `llm-connect`)

## Installation

### 1. Install from Development Head (Recommended for Daily Use)

Stay on the absolute latest code with one command:

```bash
git clone https://github.com/worsch/can-you-assist.git
cd can-you-assist
make dev-install
```

Or the direct git method (no permanent clone needed):

```bash
pip install "git+https://github.com/worsch/can-you-assist.git@main#egg=can-you-assist[dev]"
```

After installing, `cya --version` will show a development version (e.g. `0.2.0.dev48+gf500a35...`).

### 2. Install a Released Version (Future)

Once we publish official releases:

```bash
pip install can-you-assist
# or a specific version
pip install "can-you-assist>=0.3.0"
```

See `docs/release-process.md` for how releases are cut.

### Updating

```bash
cd can-you-assist
git pull
make dev-install
```

## Usage examples

```bash
# Normal request (safe path)
cya "show me the recent git history for this repo"

# Risky request — will show classification + require explicit confirmation
cya "delete every log file older than 30 days in this tree"

# See exactly what context would be collected and sent
cya --explain-context "explain the changes in the last commit"
```

The output includes a structured suggestion, rationale, and (when relevant) a
clear preview + confirmation prompt. Nothing executes without your explicit yes.

## Safety (core product behavior)

- Genuine rule-based assessment is the primary mechanism.
- Results are available to the model.
- Anything above "safe" produces a preview and blocks until you confirm in the
  launching terminal.
- No autonomous execution in this slice.

See the risk classifier tests and workplan T03 for the exact rules and invariants.

## Memory (T02 + T03 + T04 + 0003)

`cya` has real, user-controlled, context-aware memory that improves over time.

### Automatic Directory/Project-Bound Activation (T03)

Memory scoped to a directory or project is automatically activated when you work there.

```bash
# In your project directory, teach cya your preferences once
cya "remember that I always want the short git status with branch info"

# Later, in the same directory (or any subdirectory), cya will use it automatically
cya "show me the recent changes"

# No need to restate your preference — it is activated based on the working directory
```

See exactly what memory influenced a response:
```bash
cya --explain-context "show me the recent changes"
```

### Structured Retrospection & Continuous Improvement (T04)

Run a guided reflection session to review how memory was used and explicitly set goals for future interactions.

```bash
cya retrospect
```

During the session `cya` will:
- Show recent memory items that were activated.
- Help you reflect on what worked or didn't.
- Let you record new **interaction goals** (e.g. "be more concise", "always show one safe alternative for destructive commands").
- Optionally capture **1–3 verbal lessons** (Profile 1) with guided prompts, preview, and confirmation.

Example Profile 1 flow at the end of `cya retrospect`:

```
Capture 1–3 verbal lessons from this session? (y/n) y
What went well that you want to remember? (or 'skip') Safety warnings were clear
What should cya remember for next time? (or 'skip') Always suggest git status first
What should cya avoid in this scope? (or 'skip') skip

Preview — verbal lessons to save
1. [went well] Safety warnings were clear
2. [remember] Always suggest git status first

Save these lessons? (y/n) y
Saved 2 verbal reflection(s) (Profile 1).
```

These goals and lessons are stored as first-class memory and will influence future activations and responses.

### Inspecting and Controlling Memory

All memory is stored in plain, user-editable JSON:
```bash
~/.config/cya/memory/<scope>.json
```

Useful commands:
```bash
cya --explain-context "..."     # See exactly what memory was activated and why
cya memory reflections            # List verbal reflections for the current scope
cya memory reflections --json     # Export reflections as JSON
# (You can also use the memory ports directly in Python if you want to script it.)
```

Memory also feeds the safety layer: a "never auto-run" preference you set during retrospection will still force mandatory confirmation.

### Architecture Notes
- Memory lives behind explicit ports in `src/cya/memory/__init__.py`.
- Activation is automatic based on cwd + git root (with full provenance).
- Retrospection outcomes are stored with special kinds (`retrospection`, `interaction_goal`) and get preferential treatment in future context building.
- Everything is designed to be replaced/enriched by a full `phase-memory` implementation later (see MemoryVision.md).
- **Profile 0** (post-0003 local JSON + activation + retrospection loop) is the stable foundation.
- **Profile 1** (verbal reflections) is production-ready as of CYA-WP-0006: guided capture in `cya retrospect`, `cya memory reflections`, compaction, and surfacing in responses / `--explain-context`.
- Profiles 2–3 (hierarchical synthesis, procedural rules) remain roadmap items — see MemoryVision.md.

See:
- `docs/cya-memory-activation-and-retrospection-concept.md` (the T01 design)
- `workplans/CYA-WP-0003-...md`
- `src/cya/memory/__init__.py`
- `MemoryVision.md` for the long-term phase-memory vision

All memory usage is visible, explainable, and under your control. Nothing is hidden or opaque.

## Architecture & boundaries (important)

- `can-you-assist` (this repo): CLI, context collection, safety, orchestration.
- `llm-connect`: Provider access, config, token counting, structured responses.
  All interaction goes through `cya/llm/adapter.py` (`LLMAdapter` Protocol).
- `phase-memory`: Durable, user-controlled memory. Real (persisting) implementation
  lives behind the explicit ports in `cya/memory/__init__.py` (T02). Signals also flow
  into the rule-based risk layer (T04).

See `workplans/CYA-WP-0001-console-native-mvp.md` for the full task breakdown,
decisions, and integration guide.

## Development

```bash
# Recommended one-liner (see Installation section above)
make dev-install

pytest tests/ -q
cya "..."   # manual verification
make version   # show current dev version
```

## License

MIT (see LICENSE).

## Workplan & coordination

- Workplan: `workplans/CYA-WP-0001-console-native-mvp.md`
- State Hub workstream: `repo-integration-can-you-assist`
- Operator reminder after changes: `cd ~/state-hub && make fix-consistency REPO=can-you-assist`