docs + chore(workplan): complete T07 (final) for CYA-WP-0003 — heavy README Memory section, AGENTS update, MemoryVision addition, debt registration

README.md

@@ -53,30 +53,72 @@ clear preview + confirmation prompt. Nothing executes without your explicit yes.
 
 See the risk classifier tests and workplan T03 for the exact rules and invariants.
 
-## Memory (T02 + T03 + T04)
+## Memory (T02 + T03 + T04 + 0003)
 
-`cya` has real, user-controlled memory for preferences and workflow patterns.
+`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
-# Remember something for this directory / project
-cya "remember that I prefer to see git status --short --branch by default"
+# 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, cya will recall it without you restating
-cya "what is my preferred git view?"
+# Later, in the same directory (or any subdirectory), cya will use it automatically
+cya "show me the recent changes"
 
-# You can always inspect or clear what is stored
-cya --explain-context "..."          # shows memory provenance
-# The backing files live in ~/.config/cya/memory/ (plain JSON, fully user-editable)
+# No need to restate your preference — it is activated based on the working directory
 ```
 
-Memory signals also feed the safety layer: a standing "never auto-run" preference will still force mandatory confirmation even for commands the rules might otherwise treat more leniently.
+See exactly what memory influenced a response:
+```bash
+cya --explain-context "show me the recent changes"
+```
 
-All memory usage is visible and explainable. Nothing is hidden or opaque.
+### 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").
+
+These goals are stored as first-class retrospection 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
+# (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).
 
 See:
-- `src/cya/memory/__init__.py` (the explicit seam)
-- `workplans/CYA-WP-0002-memory-integration-roadmap.md`
-- `MemoryVision.md` for the longer-term direction (profile-driven phase-memory)
+- `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)