feat(memory): wire ContradictionDetector into soul note (#231 follow-up)

[prakashUXtech]

Background

Soul.note() shipped in #233 (Phase 1) and the soul remember deprecation work landed in #236 (Phase 2). One acceptance criterion from #231 is still open: contradiction detection on the dedup path.

The runtime method accepts a detect_contradictions: bool | None = None parameter (defaults to True for semantic, False for the other tiers), but the implementation at src/soul_protocol/runtime/soul.py:1497-1498 is a TODO:

# TODO: wire ContradictionDetector — see issue #231 follow-up.
_ = detect_contradictions  # currently unused; reserved for follow-up.

A working ContradictionDetector already exists at src/soul_protocol/runtime/memory/contradiction.py:123 and is wired into MemoryManager.observe() (the cognitive pipeline). The remaining work is to expose it on the note() path.

Scope

• When note() runs the dedup pipeline and the action is CREATE (the content is novel, not a SKIP/MERGE), pass the new entry through the existing ContradictionDetector.
• If a contradiction is detected against an existing semantic fact, supersede the old fact with the new one (set old.superseded_by = new.id, mirror new.supersedes = old.id, record prediction_error per the Memory updates: brain-aligned primitive set (supersede + confirm + update + weight-decay forget) #192 memory-update primitives).
• Respect the detect_contradictions parameter. The default (True for semantic, False elsewhere) stays.
• Return the supersede in the result dict so callers can branch on it. Suggested shape: extend the existing return with "contradicted_id": str | None alongside the existing action / id / existing_id / similarity fields.

Acceptance

• A semantic note() call that contradicts an existing fact returns {"action": "CREATE", "contradicted_id": "<old>", ...} and the old fact carries superseded_by
• The same call with detect_contradictions=False skips the check and returns contradicted_id: None
• Procedural / social tiers default-off behaviour preserved
• New tests cover: clean CREATE (no contradiction), CREATE with contradiction → supersede, opt-out via detect_contradictions=False, the existing SKIP/MERGE paths unchanged
• CHANGELOG entry under ## [Unreleased] / ### Memory update primitives

Out of scope

• Refactoring ContradictionDetector itself. Whatever shape it has in MemoryManager.observe() is what note() should reuse.
• New CLI flags. The existing --no-contradictions flag on soul note already maps cleanly to detect_contradictions=False (currently plumbed but a no-op).

Notes for mentees

Phase 1 of #231 left # TODO: wire ContradictionDetector as an explicit marker in the runtime, and the corresponding --no-contradictions CLI flag was plumbed without a backing implementation. Both will start working once this lands. Touches: runtime/soul.py (the TODO), the existing ContradictionDetector usage in manager.py (for the call shape), cli/main.py (verify the flag now actually has an effect), tests in tests/test_cli/ and tests/test_memory/ for the dedup-with-contradiction paths.

Tracking: closes the final acceptance item from #231.

[waqar2403]

Hi @prakashUXtech, I've implemented this locally and would like to open a PR. Quick design:

Where: Replaces the # TODO: wire ContradictionDetector at runtime/soul.py:1497 in Soul.note()'s CREATE branch. SKIP and MERGE are untouched.

Flow: After reconcile_fact() returns CREATE and remember() writes the new entry:

1. Call self._memory._contradiction_detector.detect(content, existing) against the same tier snapshot already pulled for dedup (so the new entry is never compared against itself mirrors MemoryManager.observe() step 4c).
2. Sort hits by confidence descending. For every hit: set old.superseded = True, old.superseded_by = new.id. For the top hit only: set new.supersedes = old.id and new.prediction_error = top.confidence per Memory updates: brain-aligned primitive set (supersede + confirm + update + weight-decay forget) #192.
3. Surface the top old id as contradicted_id in the return dict.

Return shape: Adds a fifth key contradicted_id: str | None alongside the existing four. None on SKIP / MERGE / clean CREATE / detect_contradictions=False the superseded id otherwise.

Defaults preserved: detect_contradictions still resolves to True for semantic, False for procedural/social/episodic. The CLI's --no-contradictions flag (previously a no-op marker) now actually disables detection.

Tests: +6 in tests/test_note/test_soul_note.py (clean CREATE, CREATE+contradiction → supersede, opt-out, procedural default-off, SKIP/MERGE shape parity) and +2 CLI smoke tests in tests/test_cli/test_note_cmd.py. All 471 contradiction / supersede / memory-primitive tests still pass no regressions.

Could you assign to me? PR ready to push.