generated from coulomb/repo-seed
tegwick
19e80cc9bc
- MemoryVision.md: Large new 'Profile 0 Baseline (Post-0003 / Current Shipped)' section with exact ports, activation logic, retrospection, safety invariants, usage sites, and relationship to 1–3 (plus the prior research section from T01). - src/cya/memory/__init__.py: Updated module docstring to declare Profile 0 reality + references to MemoryVision + CYA-WP-0005. - src/cya/orchestrator.py: Updated docstring with Profile 0 memory wiring note. - SCOPE.md: Named Profile 0 explicitly in delivered slices and core capabilities. - tests/test_memory.py: Added two new explicit 'Profile 0' tests + comments asserting provenance markers, kinds, activation_context support (T02 acceptance). - README.md + AGENTS.md: Added Profile 0 mentions + links to the workplan. All T02 acceptance criteria met. Ralph loop active. Next: T03 (full Profiles 1–3 definitions + matrix).
115 lines
8.5 KiB
Markdown
115 lines
8.5 KiB
Markdown
# 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-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 (the seed of the continuous optimization loop).
|
||
- 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 0004)
|
||
|
||
Significant slices have been delivered beyond the original MVP:
|
||
|
||
- 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. |