Retrieval Feedback Events Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Let Python callers append feedback for retrieved context so useful context reinforces decay-aware memory.

Architecture: Add MemoryFabric.record_context_feedback() as a small API over existing append(). Positive feedback writes memory.reinforced; negative feedback writes audit-only memory.feedback. Query chunks also expose entity identity so feedback can target the retrieved graph entity.

Tech Stack: Python 3.11, pytest, ruff, mypy.

---

Task 1: Feedback API Tests

Files:

• Modify: tests/test_core.py
• Modify: tests/test_query.py

• [x] Add failing tests for positive feedback writing memory.reinforced.
• [x] Add failing tests for fallback context identity.
• [x] Add failing tests for negative feedback writing memory.feedback.
• [x] Add failing tests for query chunks exposing entity name and type.

Task 2: Feedback API Implementation

Files:

• Modify: src/zaxy/core.py
• Modify: src/zaxy/query.py

• [x] Add entity identity fields to ContextChunk.
• [x] Preserve entity identity in MemoryFabric.query() context metadata.
• [x] Add record_context_feedback() using the existing append path.
• [x] Add helper normalization and fallback identity parsing.
• [x] Run focused tests and ruff.

Task 3: Docs, Verification, Commit

Files:

• Modify: docs/api.md
• Modify: docs/agent-events.md
• Modify: AGENTS.md

• [x] Document feedback events and Python API usage.
• [x] Run ruff check src tests.
• [x] Run mypy src.
• [x] Run pytest -m "not integration" --benchmark-disable --no-cov -q.
• [x] Update roadmap metrics and commit with feat: add retrieval feedback events.