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

history/2026-05-27-CYA-Intent-Scope-Gap-Analysis-Post-0002.md

@@ -0,0 +1,134 @@
+# Gap Analysis: INTENT.md vs SCOPE.md (Post CYA-WP-0002 Memory Integration)
+
+**Date:** 2026-05-27  
+**Repo:** can-you-assist  
+**Workplan:** CYA-WP-0002 (completed)  
+**Previous Analysis:** 2026-05-26 (Post 0001)  
+**Author:** Grok
+
+## Executive Summary
+
+Since the May 26 analysis (conducted immediately after CYA-WP-0001), the team has executed and completed **CYA-WP-0002 — Memory Integration Roadmap**.
+
+This work directly targeted the largest identified gap from the previous analysis: **memory, preferences, and longitudinal user-controlled adaptation**.
+
+### Key Change Since Last Analysis
+- **Memory** moved from "strictly minimal no-op ports" (T05 of 0001) to a **real, persisting, user-controlled implementation** with:
+  - JSON-backed storage under `~/.config/cya/memory/` (explicitly user-inspectable and editable)
+  - Full wiring into the orchestrator and `--explain-context`
+  - Memory signals feeding the rule-based safety layer (T04)
+  - Dedicated test coverage (T05)
+  - Documentation and examples (T06)
+- The explicit port seam defined in T01/T05 remains the long-term integration point for full `phase-memory`.
+
+**Overall Assessment**: The memory gap has been meaningfully closed for a first production-quality slice. The product now delivers on a core piece of the original INTENT that was previously missing. Other gaps remain.
+
+## Strong Alignments (Updated)
+
+| Area                              | INTENT.md Position                              | Current Reality (Post-0002)                              | Assessment          |
+|-----------------------------------|--------------------------------------------------|-----------------------------------------------------------|---------------------|
+| Console-native experience         | Foundational                                     | Excellent                                                 | Strong match        |
+| Safety & mandatory confirmation   | Important                                        | Core product behavior + memory-aware (T04)                | Exceeded            |
+| Explainability & transparency     | Strong requirement                               | Very strong (provenance in memory + context)              | Strong              |
+| Backend agnosticism               | Must use llm-connect seam                        | Clean LLMAdapter Protocol                                 | Excellent           |
+| User-controlled memory            | Central principle                                | Real implementation now exists (T02), user-visible JSON   | Major improvement   |
+| Clear boundaries                  | cya / llm-connect / phase-memory separation      | Still clearly documented                                  | Good                |
+
+## Key Gaps (Post-0002)
+
+### 1. Memory: From Largest Gap to "First Slice Delivered"
+
+**Previous Status (May 26)**: The biggest divergence. Only no-op ports existed. No real accumulation of value across sessions.
+
+**Current Status (May 27)**:
+- Real persisting memory for preferences and workflow patterns is implemented and working.
+- Users can `remember` things scoped to directories/projects and have them recalled later.
+- Memory is explainable and feeds safety.
+- Backing store is deliberately simple and user-owned (JSON files).
+
+**Remaining Sub-Gaps** (intentional per the 0002 roadmap):
+- Still a local JSON implementation, not yet wired to the full `phase-memory` profile/planner/graph system described in MemoryVision.md and phase-memory's architecture.
+- No support yet for richer memory *kinds* (conversation history as first-class fluid memory, project knowledge graphs, etc.).
+- No profile-driven lifecycle, compaction, or stabilization yet (these are owned by phase-memory).
+
+**Assessment**: Large positive movement. The "no memory at all" problem is solved for practical use. The next deepening is now a proper integration exercise rather than a foundational build.
+
+### 2. Depth of Local Context Understanding
+
+**INTENT.md** envisions rich assistance with code repositories, notes, project structures, and conventions.
+
+**Current State**:
+- Context collector remains intentionally shallow (top-level cwd entries + basic git status).
+- No recursive understanding, no semantic awareness of code or notes.
+- Memory helps with *user-declared* project conventions, but the system does not autonomously discover deep structure.
+
+**Gap Type**: Still medium-to-large. The tool is stronger for "I have a preference or pattern I want remembered" than for "understand this complex codebase for me."
+
+### 3. One-Shot vs Longitudinal / Adaptive Value
+
+**INTENT.md**:
+- Strong vision of the assistant becoming more useful over time through memory of habits, conventions, aliases, recurring workflows, preferred explanation styles, safety tolerance, etc.
+- "Personalized console helper."
+
+**Current Reality (Post-0002)**:
+- We now have the basic mechanism for this (remember/recall scoped preferences).
+- Early adaptation is possible today (users can teach `cya` their preferences).
+- However, higher-order adaptation (automatically learning patterns from accepted suggestions, building project "personalities", long-term user models) is not yet present.
+- Most usage is still fundamentally one-shot + explicit memory seeding.
+
+**Gap Type**: Reduced but still significant. The foundation for longitudinal value now exists; rich automatic adaptation is future work.
+
+### 4. Safety Implementation (Continued Positive Gap)
+
+Memory signals are now considered in risk classification (T04) while preserving the hard "never auto-execute" rule. This strengthens the original intent.
+
+**Assessment**: Remains a strength.
+
+### 5. Documentation and Perceived Scope (Meta Gap)
+
+**Observation**:
+- The current [SCOPE.md](/home/worsch/can-you-assist/SCOPE.md) still describes the world as it existed after CYA-WP-0001.
+- It continues to say memory ports are "strictly minimal no-op" and lists durable memory as out of scope.
+- This creates a documentation gap between what the code and README now deliver and what the official Scope document claims.
+
+This is a maintenance issue rather than a product gap, but it is noticeable.
+
+## Summary Table (Updated)
+
+| Gap Area                        | Severity (Post-0001) | Severity (Post-0002) | Trend      | Notes |
+|---------------------------------|----------------------|----------------------|------------|-------|
+| Memory & Adaptation             | Large                | Medium               | Much better | Real prefs + wiring delivered; full phase-memory integration pending |
+| Depth of Context Understanding  | Medium-Large         | Medium-Large         | Unchanged  | Still shallow collector |
+| Longitudinal / Automatic Adaptation | Large             | Medium               | Improved   | Foundation exists via explicit memory |
+| Safety & Explainability         | Positive             | Positive             | Stable     | Further strengthened |
+| Documentation vs Reality        | Small                | Medium               | Worsened   | SCOPE.md is now stale |
+
+## Recommendations
+
+1. **Update SCOPE.md** (high priority)
+   - Reflect post-0002 reality: real user-controlled memory now exists.
+   - Distinguish between "current implementation" (local JSON + ports) and "long-term target" (deep phase-memory integration).
+   - Move durable memory out of "explicitly out of scope."
+
+2. **Continue the Memory Roadmap**
+   - The natural next work would be deeper integration with `phase-memory` (once it exposes stable high-level APIs for preferences/project context) or richer memory kinds beyond simple key-value prefs.
+
+3. **Consider a "Context Depth" Slice**
+   - If richer repository and note understanding becomes important, a dedicated workplan focused on improving the collector + adding project memory conventions would address the second-largest remaining gap.
+
+4. **Keep the Explicit Seam Discipline**
+   - The four ports + MemoryVision contract remain the correct boundary. Future work should continue to flow through them rather than building parallel memory systems inside cya.
+
+## Conclusion
+
+CYA-WP-0002 successfully closed the most glaring hole between INTENT and delivered reality. The product now has a credible story for user-controlled memory and early personalization that was completely absent after the MVP.
+
+The remaining gaps are more about *depth and richness* of context/memory rather than the complete absence of foundational capabilities. This represents healthy progress aligned with the original vision, while maintaining the disciplined, boundary-respecting approach established in 0001.
+
+---
+
+**Related Documents**
+- Previous analysis: `history/2026-05-26-CYA-Intent-Scope-Gap-Analysis.md`
+- Memory vision: `MemoryVision.md`
+- Completed memory workplan: `workplans/CYA-WP-0002-memory-integration-roadmap.md`
+- Current (stale) scope: `SCOPE.md` (recommended for update)