# 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)