docs: update SCOPE.md post-0004 + new gap analysis (2026-05-28) vs INTENT.md

SCOPE.md

@@ -6,23 +6,27 @@
 
 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)
+## Current Status (Post CYA-WP-0004 Packaging & Distribution Slice)
 
-Two implementation slices have been delivered:
+Four 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.
+- **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).
+- **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 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.
+- 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 (directory/project scoped) with retrospection support.
+- Automatic memory activation based on working directory/git root.
+- `cya retrospect` for structured reflection and goal setting.
+- 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. No production path bypasses these boundaries.
+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
 
@@ -44,7 +48,7 @@ All LLM interaction flows through the documented adapter seam. Memory flows thro
 - 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.
+- 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
@@ -52,56 +56,59 @@ All LLM interaction flows through the documented adapter seam. Memory flows thro
 | 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 |
+| `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)           |
 
-## MVP Scope (CYA-WP-0001)
+## Current Delivered Scope (Post 0004)
 
-What was explicitly in scope for the first slice:
+Significant slices have been delivered beyond the original MVP:
 
-- 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.
+- 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 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).
+- 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 four explicit ports with real (persisting, user-controlled) implementation behind them.
-- `cya/safety/risk.py` — the `_RULES` table and `classify()` function.
+- `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 Slice)
+## Success Criteria (Current State)
 
-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`.
+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.
-- See a clear path for how real `llm-connect` and `phase-memory` will plug in later.
+- 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 can read the workplan + boundary documentation and know precisely where their packages 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-0001 (MVP) + CYA-WP-0002 (Memory Integration).**
+**This SCOPE document reflects the state after CYA-WP-0004 (Dev-Head Install & Release Packaging).**
 
-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.
+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 `workplans/CYA-WP-0002-memory-integration-roadmap.md` and `MemoryVision.md` for the intended direction of deeper `phase-memory` integration.
+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.