Reflection

Reflection

What reflection is for

Memory accretes: duplicate notes, stale overdue tasks, empty drafts, abandoned inbox items, entities with nothing on them. Reflection is the scheduled tidy-up: consolidation proposed by the platform, decided by a human (or a trusted reviewer), applied as ordinary audited mutations. Nothing consolidates itself silently.

The pipeline

1. Audit: reflect_audit scans without changing anything and returns consolidation candidates (duplicate titles, stale overdue work, empty notes, orphan parents, abandoned inbox items, observation-less entities), each with a suggested action.
2. Start: reflect_start opens a run and persists its candidates for review.
3. Review and decide: reflect_review pages candidates with filters; reflect_decide records accept, reject, or defer per candidate.
4. Apply: reflect_apply executes accepted candidates through the normal task mutation path with before/after snapshots. Already-applied candidates skip idempotently; vanished or denied targets skip with reasons rather than failing the run.
5. Close out: reflect_status watches progress; reflect_history lists runs; reflect_cancel stops an active run; reflect_archive shelves a terminal one; reflect_discard retires a terminal run as a lifecycle transition; review evidence stays usable while the run itself resolves as absent.

Context assessment and clarification

Running alongside the pipeline is the context loop: assess_context classifies a context chunk and detects its signals; queue_clarification locks the chunk behind focused questions for a human; record_human_answer ingests the answer and re-opens the chunk. audit_memory runs the self-repair loop over facts and provenance; replay_memory replays the append-only event history for any aggregate; list_memory_issues lists what the last audit found. explain_impact shows what a knowledge change touches downstream before it is made.

Claims and governance

extract_candidate_claims pulls typed claims from context; promote_candidate governs their promotion to canonical facts; sensitive scopes require explicit human confirmation, never auto-promotion; govern_fact maintains truth afterwards (supersede, contradict, invalidate, revalidate). Candidates without evidence stay candidates.

Boundaries worth knowing

• Audit scans honour project grants; unfiltered runs need broad scope.
• Applying respects per-target scope at mutation time: denied targets skip as out-of-scope rather than failing others.
• Engine failures arrive as normal error payloads, never transport errors; reflect calls never surprise a client with a protocol fault for a domain problem.
• Discard is the narrow sanctioned retirement: it is a transition with timestamp, actor, and reason: the one way runs end without losing review evidence, and the reason hard deletion stays unnecessary.