From 28869cae67cce490a6d4ddb8436e0e9ab2626115 Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 02:32:37 +0530
Subject: [PATCH 01/10] refactor(.agent): host-agent review protocol +
 structural fixes

Shifts the reasoning boundary: Python handles mechanical filing
(cluster, extract, stage, prefilter, decay, archive). The host agent
(Claude Code, Codex, Windsurf, ...) handles validation via CLI tools
using the LLM it already has. The brain no longer needs its own
ANTHROPIC_API_KEY.

Bug fixes
- promote.graduate_validated batch-unsoundness (fixed then the function
  was removed; replaced by tools/graduate.py which handles one candidate
  at a time against a fresh LESSONS.md read).
- hooks/on_failure.py: rewrite-flag off-by-one (was firing on 4th
  failure; now 3rd, as FAILURE_THRESHOLD=3 implies).
- hooks/post_execution.py + on_failure.py: ornamental `contradicts`
  field removed from episodic writes (never populated on raw events).

Restructure
- memory/auto_dream.py: staging-only. No validation, no graduation,
  no git commit. Safe to run on Stop hooks or cron.
- memory/validate.py: gutted to heuristic prefilter (length + exact
  duplicate). No LLM calls. No more Anthropic SDK coupling.
- memory/review_state.py (new): candidate lifecycle (staged /
  provisional / accepted / rejected / superseded) + append-only
  decision log. rejection_count + reopen history surface recurring
  churn instead of looking fresh.
- memory/render_lessons.py (new): semantic/lessons.jsonl is the
  source of truth; LESSONS.md is rendered. User content above the
  `## Auto-promoted entries will be appended below` sentinel is
  preserved across renders.
- memory/cluster.py (new): Jaccard content clustering + deterministic
  extractive pattern (canonical highest-salience episode as claim).
  Replaces action-prefix clustering.
- harness/context_budget.py: query-aware retrieval (salience x
  relevance). Loads AGENTS.md, DECISIONS.md, REVIEW_QUEUE.md per
  the stated read order (previously silently skipped).
- harness/llm.py (new): _call_model factored out of conductor.
  Used only by the standalone conductor path; memory/ no longer
  imports it.
- harness/text.py (new): shared STOPWORDS, word_set, jaccard.
- harness/hooks/_provenance.py (new): source metadata for
  episodic entries (confidence, source{skill, run_id, commit_sha},
  evidence_ids).
- tools/list_candidates.py, graduate.py, reject.py, reopen.py (new):
  host-agent CLI. Graduation requires --rationale so silent
  rubber-stamp is structurally impossible.

Host-agent review protocol
- auto_dream stages candidates + writes memory/working/REVIEW_QUEUE.md
- Host agent checks the queue at session start
- list_candidates.py to see pending (priority = cluster_size *
  canonical_salience * age_factor)
- graduate.py <id> --rationale "..." or reject.py <id> --reason "..."
- Review is batched so cross-candidate contradictions surface
- Heuristic prefilter catches obvious junk; subjective judgment is
  the host agent's, not the brain's

Addresses Codex review of the earlier draft
- Batch-unsound graduate_validated: removed; per-call graduate.py reads
  fresh LESSONS.md each time.
- Unattended reasoning + git commits on Stop hook: stripped to
  staging-only.
- Provider coupling in validate.py: removed.
- Fragile candidate state: durable lifecycle + decision log.
- AGENTS.md / DECISIONS.md not loaded despite stated contract: now
  loaded.
- Off-by-one rewrite trigger: fixed.
- Anecdote-as-claim extraction: unchanged; mitigated by host-agent
  review. (Upgrading extraction is Phase 4 work.)

Not pushed (stays per-user)
- memory/personal/PREFERENCES.md
- memory/working/WORKSPACE.md
- memory/working/REVIEW_QUEUE.md (regenerated by auto_dream)
- memory/episodic/AGENT_LEARNINGS.jsonl
- memory/candidates/
- memory/semantic/lessons.jsonl (grows from graduations)
---
 .agent/AGENTS.md                       |  40 ++++-
 .agent/harness/conductor.py            |  27 +---
 .agent/harness/context_budget.py       | 128 +++++++++++++---
 .agent/harness/hooks/_provenance.py    |  33 ++++
 .agent/harness/hooks/on_failure.py     |  11 +-
 .agent/harness/hooks/post_execution.py |   6 +-
 .agent/harness/llm.py                  |  38 +++++
 .agent/harness/text.py                 |  30 ++++
 .agent/memory/auto_dream.py            |  91 ++++++++---
 .agent/memory/cluster.py               |  82 ++++++++++
 .agent/memory/promote.py               | 104 ++++++++-----
 .agent/memory/render_lessons.py        | 123 +++++++++++++++
 .agent/memory/review_state.py          | 203 +++++++++++++++++++++++++
 .agent/memory/validate.py              |  79 ++++++++++
 .agent/tools/graduate.py               |  84 ++++++++++
 .agent/tools/list_candidates.py        |  62 ++++++++
 .agent/tools/memory_reflect.py         |  16 +-
 .agent/tools/reject.py                 |  38 +++++
 .agent/tools/reopen.py                 |  34 +++++
 19 files changed, 1109 insertions(+), 120 deletions(-)
 create mode 100644 .agent/harness/hooks/_provenance.py
 create mode 100644 .agent/harness/llm.py
 create mode 100644 .agent/harness/text.py
 create mode 100644 .agent/memory/cluster.py
 create mode 100644 .agent/memory/render_lessons.py
 create mode 100644 .agent/memory/review_state.py
 create mode 100644 .agent/memory/validate.py
 create mode 100644 .agent/tools/graduate.py
 create mode 100644 .agent/tools/list_candidates.py
 create mode 100644 .agent/tools/reject.py
 create mode 100644 .agent/tools/reopen.py

diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md
index 4191b53..c324b26 100644
--- a/.agent/AGENTS.md
+++ b/.agent/AGENTS.md
@@ -7,10 +7,34 @@ same memory, skills, and protocols.
 ## Memory (read in this order)
 - `memory/personal/PREFERENCES.md` — stable user conventions
 - `memory/working/WORKSPACE.md` — current task state
-- `memory/semantic/LESSONS.md` — distilled patterns, read before decisions
+- `memory/working/REVIEW_QUEUE.md` — pending candidate lessons waiting for you
 - `memory/semantic/DECISIONS.md` — past architectural choices
+- `memory/semantic/LESSONS.md` — distilled patterns (rendered from `lessons.jsonl`)
 - `memory/episodic/AGENT_LEARNINGS.jsonl` — raw experience log (top-k by salience)
 
+## Review Queue (host-agent responsibility)
+
+Candidate lessons are clustered + staged automatically by `memory/auto_dream.py`.
+The host agent — you — does the actual review using the CLI tools below.
+
+Check `memory/working/REVIEW_QUEUE.md` at session start. If pending > 10 or
+oldest staged > 7 days, review before substantive work.
+
+Workflow:
+1. `python .agent/tools/list_candidates.py` — pending candidates, sorted by priority
+2. For each: decide accept / reject / defer based on claim, evidence_ids,
+   cluster_size, and any contradictions with existing LESSONS.md
+3. `python .agent/tools/graduate.py <id> --rationale "..."` to accept
+4. `python .agent/tools/reject.py <id> --reason "..."` to reject
+5. `python .agent/tools/reopen.py <id>` to requeue a previously-rejected item
+6. Review in a **batch**, not one-by-one — cross-candidate contradictions
+   only surface when you see multiple at once.
+
+The heuristic prefilter in `memory/validate.py` has already dropped obvious
+junk (too-short claims, exact duplicates). Everything staged needs real
+judgment. Rationale is required for graduation — rubber-stamped promotions
+are the exact failure mode this layer prevents.
+
 ## Skills
 - `skills/_index.md` — read first for discovery
 - `skills/_manifest.jsonl` — machine-readable skill metadata
@@ -24,8 +48,12 @@ same memory, skills, and protocols.
 
 ## Rules
 1. Check memory before decisions you have been corrected on before.
-2. Log every significant action to `memory/episodic/AGENT_LEARNINGS.jsonl`.
-3. Update `memory/working/WORKSPACE.md` as you work; archive on completion.
-4. Follow `protocols/permissions.md` strictly. Blocked means blocked.
-5. When a self-rewrite hook fires, propose conservative edits only.
-6. The harness is dumb on purpose. Reasoning lives in skills and memory.
+2. If `REVIEW_QUEUE.md` shows backlog past threshold, handle it before the new task.
+3. Log every significant action to `memory/episodic/AGENT_LEARNINGS.jsonl`
+   via `.agent/tools/memory_reflect.py`.
+4. Update `memory/working/WORKSPACE.md` as you work; archive on completion.
+5. Never hand-edit `memory/semantic/LESSONS.md` — it's rendered from
+   `lessons.jsonl`. Use `graduate.py` / `reject.py` instead.
+6. Follow `protocols/permissions.md`. Blocked means blocked.
+7. When a self-rewrite hook fires, propose conservative edits only.
+8. The harness is dumb on purpose. Reasoning lives in skills + the host agent.
diff --git a/.agent/harness/conductor.py b/.agent/harness/conductor.py
index a19e90a..ad5a051 100644
--- a/.agent/harness/conductor.py
+++ b/.agent/harness/conductor.py
@@ -2,35 +2,12 @@
 import os, sys
 from context_budget import build_context
 from hooks.post_execution import log_execution
+from llm import call_model
 
 RESERVED = 40000
 MAX_CTX = int(os.getenv("AGENT_MAX_CONTEXT", "128000"))
 
 
-def _call_model(system, user):
-    provider = os.getenv("AGENT_PROVIDER", "anthropic").lower()
-    if provider == "anthropic":
-        from anthropic import Anthropic
-        c = Anthropic()
-        r = c.messages.create(
-            model=os.getenv("AGENT_MODEL", "claude-sonnet-4-5"),
-            max_tokens=4096, temperature=0.3,
-            system=system,
-            messages=[{"role": "user", "content": user}],
-        )
-        return r.content[0].text
-    if provider == "openai":
-        from openai import OpenAI
-        c = OpenAI()
-        r = c.chat.completions.create(
-            model=os.getenv("AGENT_MODEL", "gpt-4o"),
-            messages=[{"role": "system", "content": system},
-                      {"role": "user", "content": user}],
-        )
-        return r.choices[0].message.content
-    raise ValueError(f"unknown provider: {provider}")
-
-
 SYSTEM_PREAMBLE = (
     "You are an agent with externalized memory, skills, and protocols.\n"
     "Your memory, skills, and constraints are in the context below.\n"
@@ -43,7 +20,7 @@ def run(user_input: str) -> str:
     context, used = build_context(user_input, budget=MAX_CTX - RESERVED)
     system = SYSTEM_PREAMBLE + context
     try:
-        result = _call_model(system, user_input)
+        result = call_model(system, user_input)
         log_execution("conductor", user_input[:100], result[:500], True)
         return result
     except Exception as e:
diff --git a/.agent/harness/context_budget.py b/.agent/harness/context_budget.py
index 4068e43..67692c5 100644
--- a/.agent/harness/context_budget.py
+++ b/.agent/harness/context_budget.py
@@ -1,8 +1,19 @@
-"""Assemble context from memory + matched skills + protocols within a token budget."""
-import json, os
+"""Assemble context from memory + matched skills + protocols within a token budget.
+
+Query-aware: episodes and lessons are scored against user_input so the agent
+sees the memory that matters for *this* task, not just the most salient memory
+in general. Always-on slots (PREFERENCES, WORKSPACE, permissions) are loaded
+whole regardless of query — they're cheap and safety-critical.
+"""
+import json, os, sys
 from salience import salience_score
+from text import word_set, jaccard
 
 ROOT = os.path.join(os.path.dirname(__file__), "..")
+# skill_loader lives in tools/ — make it importable without requiring callers
+# to configure PYTHONPATH themselves
+sys.path.insert(0, os.path.join(ROOT, "tools"))
+RELEVANCE_FLOOR = 0.3  # even zero-overlap episodes surface if very salient
 
 
 def _read(path, limit=None):
@@ -13,11 +24,22 @@ def _read(path, limit=None):
     return content[:limit] if limit else content
 
 
-def _tokens(text):
+def _token_estimate(text):
+    """Rough chars-to-tokens estimate for budgeting."""
     return len(text) // 4
 
 
-def _top_episodes(k=5):
+def _relevance(entry_text, query_words):
+    """Fraction of query words that appear in entry. 1.0 when no query."""
+    if not query_words:
+        return 1.0
+    ew = word_set(entry_text)
+    if not ew:
+        return 0.0
+    return len(query_words & ew) / len(query_words)
+
+
+def _top_episodes(query, k=5):
     path = os.path.join(ROOT, "memory/episodic/AGENT_LEARNINGS.jsonl")
     if not os.path.exists(path):
         return ""
@@ -30,7 +52,19 @@ def _top_episodes(k=5):
             entries.append(json.loads(line))
         except json.JSONDecodeError:
             continue
-    entries.sort(key=salience_score, reverse=True)
+
+    query_words = word_set(query)
+
+    def _score(e):
+        text = " ".join([
+            e.get("action", ""),
+            e.get("reflection", ""),
+            e.get("detail", ""),
+        ])
+        rel = _relevance(text, query_words)
+        return salience_score(e) * (RELEVANCE_FLOOR + (1.0 - RELEVANCE_FLOOR) * rel)
+
+    entries.sort(key=_score, reverse=True)
     top = entries[:k]
     return "\n".join(
         f"- [{e.get('timestamp','')[:10]}] {e.get('action','')}: "
@@ -39,38 +73,88 @@ def _top_episodes(k=5):
     )
 
 
+def _lines_up_to_budget(lines, char_budget):
+    out, used = [], 0
+    for line in lines:
+        block = f"- {line}\n"
+        if used + len(block) > char_budget:
+            break
+        out.append(block)
+        used += len(block)
+    return "".join(out)
+
+
+def _top_lessons(query, lessons_md, char_budget=8000):
+    """Rank LESSONS.md bullets by query overlap; fall back to original order.
+
+    Section headers (## ...) get dropped when ranking — the LLM only needs
+    the distilled claim lines. When the query has zero overlap with any
+    bullet, fall back to the original order so the agent still sees general
+    knowledge.
+    """
+    lines = []
+    for line in (lessons_md or "").splitlines():
+        s = line.strip()
+        if s.startswith("- ") and len(s) > 2:
+            lines.append(s[2:].split("<!--")[0].strip())
+    if not lines:
+        return lessons_md[:char_budget]
+
+    query_words = word_set(query)
+    if not query_words:
+        return _lines_up_to_budget(lines, char_budget)
+
+    scored = [(len(query_words & word_set(l)), i, l) for i, l in enumerate(lines)]
+    relevant = sorted([s for s in scored if s[0] > 0], key=lambda s: (-s[0], s[1]))
+
+    if not relevant:
+        return _lines_up_to_budget(lines, char_budget)
+    return _lines_up_to_budget([l for _, _, l in relevant], char_budget)
+
+
 def build_context(user_input: str, budget: int = 88000):
-    """Returns (context_string, tokens_used). Lean by design."""
-    from skill_loader import progressive_load  # lazy to avoid cycles
+    """Returns (context_string, tokens_used). Lean and query-aware."""
     parts, used = [], 0
 
-    # always load: personal preferences + live workspace
-    for rel in ("memory/personal/PREFERENCES.md", "memory/working/WORKSPACE.md"):
+    # always load: personal preferences + live workspace + AGENTS map + DECISIONS
+    # AGENTS.md and DECISIONS.md were missing despite AGENTS.md specifying the
+    # read order — the standalone path was not faithful to its own contract.
+    for rel in (
+        "AGENTS.md",
+        "memory/personal/PREFERENCES.md",
+        "memory/working/WORKSPACE.md",
+        "memory/working/REVIEW_QUEUE.md",
+        "memory/semantic/DECISIONS.md",
+    ):
         text = _read(rel)
         if text:
             parts.append(f"# {rel}\n{text}")
-            used += _tokens(text)
+            used += _token_estimate(text)
 
-    # semantic lessons, truncated
-    lessons = _read("memory/semantic/LESSONS.md", limit=8000)
-    if lessons:
-        parts.append(f"# LESSONS\n{lessons}")
-        used += _tokens(lessons)
+    # query-aware lessons
+    lessons_raw = _read("memory/semantic/LESSONS.md")
+    if lessons_raw:
+        lessons = _top_lessons(user_input, lessons_raw, char_budget=8000)
+        if lessons:
+            parts.append(f"# LESSONS (query-relevant)\n{lessons}")
+            used += _token_estimate(lessons)
 
-    # top episodic by salience
-    episodes = _top_episodes(k=5)
+    # query-aware top episodes
+    episodes = _top_episodes(user_input, k=5)
     if episodes:
-        parts.append(f"# RECENT EPISODES (top by salience)\n{episodes}")
-        used += _tokens(episodes)
+        parts.append(f"# RECENT EPISODES (salience x relevance)\n{episodes}")
+        used += _token_estimate(episodes)
 
-    # matched skills only
+    # matched skills only (progressive_load is already input-matched).
+    # Lazy import so a missing skill_loader doesn't kill context assembly.
     try:
+        from skill_loader import progressive_load
         skills = progressive_load(user_input)
     except Exception:
         skills = []
     for s in skills:
         block = f"## Skill: {s['name']}\n{s['content']}"
-        t = _tokens(block)
+        t = _token_estimate(block)
         if used + t < budget:
             parts.append(block)
             used += t
@@ -79,6 +163,6 @@ def build_context(user_input: str, budget: int = 88000):
     perms = _read("protocols/permissions.md")
     if perms:
         parts.append(f"# PERMISSIONS\n{perms}")
-        used += _tokens(perms)
+        used += _token_estimate(perms)
 
     return "\n\n---\n\n".join(parts), used
diff --git a/.agent/harness/hooks/_provenance.py b/.agent/harness/hooks/_provenance.py
new file mode 100644
index 0000000..0228697
--- /dev/null
+++ b/.agent/harness/hooks/_provenance.py
@@ -0,0 +1,33 @@
+"""Shared provenance helpers for episodic entries. Cached per-process."""
+import os, subprocess
+
+AGENT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+
+_CACHED_COMMIT = None
+_CACHED_RUN_ID = None
+
+
+def run_id():
+    global _CACHED_RUN_ID
+    if _CACHED_RUN_ID is None:
+        _CACHED_RUN_ID = os.environ.get("AGENT_RUN_ID", f"pid-{os.getpid()}")
+    return _CACHED_RUN_ID
+
+
+def commit_sha():
+    global _CACHED_COMMIT
+    if _CACHED_COMMIT is None:
+        try:
+            out = subprocess.run(
+                ["git", "rev-parse", "HEAD"],
+                capture_output=True, text=True, timeout=2,
+                cwd=AGENT_ROOT,
+            )
+            _CACHED_COMMIT = out.stdout.strip() if out.returncode == 0 else ""
+        except Exception:
+            _CACHED_COMMIT = ""
+    return _CACHED_COMMIT
+
+
+def build_source(skill):
+    return {"skill": skill, "run_id": run_id(), "commit_sha": commit_sha()}
diff --git a/.agent/harness/hooks/on_failure.py b/.agent/harness/hooks/on_failure.py
index 6870d33..850ff7f 100644
--- a/.agent/harness/hooks/on_failure.py
+++ b/.agent/harness/hooks/on_failure.py
@@ -1,5 +1,6 @@
 """Failures are learning. High pain score + rewrite flag after repeat offenses."""
 import json, datetime, os
+from ._provenance import build_source
 
 ROOT = os.path.join(os.path.dirname(__file__), "..", "..")
 EPISODIC = os.path.join(ROOT, "memory/episodic/AGENT_LEARNINGS.jsonl")
@@ -30,7 +31,8 @@ def _count_recent_failures(skill_name):
     return count
 
 
-def on_failure(skill_name, action, error, context=""):
+def on_failure(skill_name, action, error, context="", confidence=0.9,
+               evidence_ids=None):
     entry = {
         "timestamp": datetime.datetime.now().isoformat(),
         "skill": skill_name,
@@ -42,8 +44,13 @@ def on_failure(skill_name, action, error, context=""):
         "reflection": f"FAILURE in {skill_name}: {type(error).__name__}: "
                       f"{str(error)[:200]}",
         "context": context[:300],
+        "confidence": confidence,
+        "source": build_source(skill_name),
+        "evidence_ids": list(evidence_ids) if evidence_ids else [],
     }
-    recent = _count_recent_failures(skill_name)
+    # _count_recent_failures returns PRIOR failures only; add 1 for this one
+    # so the rewrite flag fires on the Nth failure, not the (N+1)th.
+    recent = _count_recent_failures(skill_name) + 1
     if recent >= FAILURE_THRESHOLD:
         entry["reflection"] += (
             f" | THIS SKILL HAS FAILED {recent} TIMES IN {WINDOW_DAYS}d. "
diff --git a/.agent/harness/hooks/post_execution.py b/.agent/harness/hooks/post_execution.py
index d3d590a..7bc90f4 100644
--- a/.agent/harness/hooks/post_execution.py
+++ b/.agent/harness/hooks/post_execution.py
@@ -1,12 +1,13 @@
 """Runs after every action. Appends a structured entry to episodic memory."""
 import json, datetime, os
+from ._provenance import build_source
 
 ROOT = os.path.join(os.path.dirname(__file__), "..", "..")
 EPISODIC = os.path.join(ROOT, "memory/episodic/AGENT_LEARNINGS.jsonl")
 
 
 def log_execution(skill_name, action, result, success, reflection="",
-                  importance=5):
+                  importance=5, confidence=0.5, evidence_ids=None):
     os.makedirs(os.path.dirname(EPISODIC), exist_ok=True)
     entry = {
         "timestamp": datetime.datetime.now().isoformat(),
@@ -17,6 +18,9 @@ def log_execution(skill_name, action, result, success, reflection="",
         "pain_score": 2 if success else 7,
         "importance": importance,
         "reflection": reflection,
+        "confidence": confidence,
+        "source": build_source(skill_name),
+        "evidence_ids": list(evidence_ids) if evidence_ids else [],
     }
     with open(EPISODIC, "a") as f:
         f.write(json.dumps(entry) + "\n")
diff --git a/.agent/harness/llm.py b/.agent/harness/llm.py
new file mode 100644
index 0000000..082969a
--- /dev/null
+++ b/.agent/harness/llm.py
@@ -0,0 +1,38 @@
+"""Shared model-call helper. Factored out of conductor so memory/ can reuse."""
+import os
+
+
+def llm_available():
+    """True iff provider + key are configured. Validation / dream cycle check
+    this before making calls so they degrade gracefully offline."""
+    provider = os.getenv("AGENT_PROVIDER", "anthropic").lower()
+    if provider == "anthropic":
+        return bool(os.getenv("ANTHROPIC_API_KEY"))
+    if provider == "openai":
+        return bool(os.getenv("OPENAI_API_KEY"))
+    return False
+
+
+def call_model(system, user, *, temperature=0.3, max_tokens=4096, model=None):
+    provider = os.getenv("AGENT_PROVIDER", "anthropic").lower()
+    if provider == "anthropic":
+        from anthropic import Anthropic
+        c = Anthropic()
+        r = c.messages.create(
+            model=model or os.getenv("AGENT_MODEL", "claude-sonnet-4-5"),
+            max_tokens=max_tokens, temperature=temperature,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+        return r.content[0].text
+    if provider == "openai":
+        from openai import OpenAI
+        c = OpenAI()
+        r = c.chat.completions.create(
+            model=model or os.getenv("AGENT_MODEL", "gpt-4o"),
+            temperature=temperature,
+            messages=[{"role": "system", "content": system},
+                      {"role": "user", "content": user}],
+        )
+        return r.choices[0].message.content
+    raise ValueError(f"unknown provider: {provider}")
diff --git a/.agent/harness/text.py b/.agent/harness/text.py
new file mode 100644
index 0000000..8d8babf
--- /dev/null
+++ b/.agent/harness/text.py
@@ -0,0 +1,30 @@
+"""Shared text utilities for memory/retrieval scoring.
+
+Single source of truth for stopwords + lexical overlap. Both validate.py
+(dream-cycle promotion gate) and context_budget.py (retrieval) depend on it,
+so drift here would quietly make the two layers see different words.
+"""
+import re
+
+STOPWORDS = frozenset({
+    "the", "a", "an", "and", "or", "but", "is", "are", "was", "were", "be",
+    "been", "being", "have", "has", "had", "do", "does", "did", "will",
+    "would", "should", "could", "may", "might", "must", "can", "this",
+    "that", "these", "those", "of", "in", "on", "at", "to", "for", "with",
+    "by", "from", "as", "if", "then", "when", "where", "how", "why", "what",
+    "it", "its", "their", "our", "we", "you", "i", "not", "no",
+})
+
+
+def word_set(text):
+    """Lowercase content words (3+ chars, stopwords removed)."""
+    return {t.lower() for t in re.findall(r"[a-zA-Z][a-zA-Z0-9_-]{2,}", text or "")
+            if t.lower() not in STOPWORDS}
+
+
+def jaccard(a, b):
+    if not a and not b:
+        return 1.0
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
diff --git a/.agent/memory/auto_dream.py b/.agent/memory/auto_dream.py
index 75f4cd7..8d5f3d7 100644
--- a/.agent/memory/auto_dream.py
+++ b/.agent/memory/auto_dream.py
@@ -1,13 +1,32 @@
-"""Nightly compression. Orchestrates promote + decay + archive + git snapshot."""
-import json, os, datetime, subprocess
-from promote import find_recurring_patterns, promote_to_semantic
+"""Staging-only dream cycle. Mechanical work, no reasoning.
+
+Responsibilities (in order):
+  1. load episodic entries
+  2. cluster + extract → structured patterns
+  3. stage candidates (lifecycle metadata baked in)
+  4. heuristic prefilter (length + exact-duplicate; obvious junk goes to rejected/)
+  5. decay old episodes + archive stale workspace
+  6. write REVIEW_QUEUE.md summary so the next host session sees the backlog
+
+Never:
+  - subjective validation (host agent reviews via CLI tools)
+  - promotion to LESSONS.md (graduate.py does that)
+  - git commit (unattended repo writes are dangerous on a host hook)
+"""
+import json, os
+from promote import cluster_and_extract, write_candidates
+from validate import heuristic_check
+from review_state import mark_rejected, write_review_queue_summary
 from decay import decay_old_entries
 from archive import archive_stale_workspace
 
-ROOT = os.path.abspath(os.path.dirname(__file__))  # .agent/memory/ — absolute so cron paths hold
-PROJ_ROOT = os.path.dirname(os.path.dirname(ROOT))   # project root
+ROOT = os.path.abspath(os.path.dirname(__file__))
 EPISODIC = os.path.join(ROOT, "episodic/AGENT_LEARNINGS.jsonl")
+CANDIDATES = os.path.join(ROOT, "candidates")
+SEMANTIC = os.path.join(ROOT, "semantic")
+REVIEW_QUEUE = os.path.join(ROOT, "working/REVIEW_QUEUE.md")
 PROMOTION_THRESHOLD = 7.0
+CLUSTER_SIMILARITY = 0.3
 
 
 def _load_entries():
@@ -31,14 +50,34 @@ def _write_entries(entries):
             f.write(json.dumps(e) + "\n")
 
 
-def _git_snapshot(promoted, decayed, kept):
-    msg = f"dream cycle: promoted {promoted}, decayed {decayed}, kept {kept}"
-    try:
-        subprocess.run(["git", "add", ROOT], check=False, cwd=PROJ_ROOT)
-        subprocess.run(["git", "commit", "-m", msg], check=False, cwd=PROJ_ROOT)
-    except FileNotFoundError:
-        pass
-    return msg
+def _heuristic_prefilter(candidates_dir, semantic_dir):
+    """Move obvious junk (too-short, exact duplicate) to rejected/ automatically.
+
+    Anything subjective — "is this really a useful lesson?" — is the host
+    agent's call, not this function's.
+    """
+    if not os.path.isdir(candidates_dir):
+        return 0
+    lessons_path = os.path.join(semantic_dir, "LESSONS.md")
+    existing = open(lessons_path).read() if os.path.exists(lessons_path) else ""
+    rejected = 0
+    for fname in sorted(os.listdir(candidates_dir)):
+        if not fname.endswith(".json"):
+            continue
+        path = os.path.join(candidates_dir, fname)
+        if not os.path.isfile(path):
+            continue
+        try:
+            with open(path) as f:
+                cand = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            continue
+        check = heuristic_check(cand, existing)
+        if not check["passed"]:
+            reason = ", ".join(check["reasons"])
+            mark_rejected(cand["id"], "heuristic_prefilter", reason, candidates_dir)
+            rejected += 1
+    return rejected
 
 
 def run_dream_cycle():
@@ -47,17 +86,27 @@ def run_dream_cycle():
         print("dream cycle: no entries")
         return
 
-    recurring = find_recurring_patterns(entries)
-    promotable = [e for e in recurring.values()
-                  if e.get("_salience", 0) >= PROMOTION_THRESHOLD]
-    promoted = promote_to_semantic(promotable, semantic_dir=os.path.join(ROOT, "semantic"))
+    patterns = cluster_and_extract(entries, threshold=CLUSTER_SIMILARITY)
+    promotable = {k: p for k, p in patterns.items()
+                  if p.get("canonical_salience", 0) >= PROMOTION_THRESHOLD}
 
-    kept, archived = decay_old_entries(entries, archive_dir=os.path.join(ROOT, "episodic/snapshots"))
+    staged = write_candidates(promotable, CANDIDATES)
+    prefiltered = _heuristic_prefilter(CANDIDATES, SEMANTIC)
+
+    kept, archived = decay_old_entries(
+        entries, archive_dir=os.path.join(ROOT, "episodic/snapshots"))
     _write_entries(kept)
-    archive_stale_workspace(working_dir=os.path.join(ROOT, "working"),
-                            archive_dir=os.path.join(ROOT, "episodic/snapshots"))
+    archive_stale_workspace(
+        working_dir=os.path.join(ROOT, "working"),
+        archive_dir=os.path.join(ROOT, "episodic/snapshots"))
+
+    pending = write_review_queue_summary(CANDIDATES, REVIEW_QUEUE)
 
-    print(_git_snapshot(promoted, len(archived), len(kept)))
+    print(
+        f"dream cycle: patterns={len(patterns)} staged={staged} "
+        f"prefiltered_out={prefiltered} pending_review={pending} "
+        f"archived={len(archived)} kept={len(kept)}"
+    )
 
 
 if __name__ == "__main__":
diff --git a/.agent/memory/cluster.py b/.agent/memory/cluster.py
new file mode 100644
index 0000000..472f964
--- /dev/null
+++ b/.agent/memory/cluster.py
@@ -0,0 +1,82 @@
+"""Content-based clustering + deterministic pattern extraction.
+
+Phase 3's replacement for action-prefix clustering. Works without an LLM:
+similarity is Jaccard on word_set, and extraction picks a canonical episode
+rather than synthesizing a new claim. Structured candidates flow through the
+Phase 1 validation gate — if no LLM is available, they defer as before.
+"""
+import os, sys, hashlib
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "harness"))
+from text import word_set, jaccard
+from salience import salience_score
+
+
+def _entry_features(entry):
+    """Content feature set for clustering: action + reflection + detail."""
+    text = " ".join([
+        entry.get("action", ""),
+        entry.get("reflection", ""),
+        entry.get("detail", ""),
+    ])
+    return word_set(text)
+
+
+def content_cluster(entries, threshold=0.3, min_size=2):
+    """Single-linkage agglomerative clustering on Jaccard similarity.
+
+    An entry joins the first cluster where any member's similarity meets
+    threshold. Entries with empty feature sets are dropped (they can't
+    cluster meaningfully — jaccard on two empty sets returns 1.0 in the
+    shared helper, so we filter here rather than fight the math).
+
+    Returns only clusters with >= min_size members so singletons don't
+    create candidate churn.
+    """
+    featured = [(e, _entry_features(e)) for e in entries]
+    featured = [(e, fs) for e, fs in featured if fs]
+
+    clusters = []  # each: list of (entry, feature_set)
+    for item in featured:
+        e_i, fs_i = item
+        joined = False
+        for c in clusters:
+            if any(jaccard(fs_i, fs_j) >= threshold for _, fs_j in c):
+                c.append(item)
+                joined = True
+                break
+        if not joined:
+            clusters.append([item])
+
+    return [[e for e, _ in c] for c in clusters if len(c) >= min_size]
+
+
+def extract_pattern(cluster):
+    """Extractive summarization from a cluster of episodes.
+
+    Without an LLM we cannot synthesize a generalization, so:
+      - claim: canonical (highest-salience) member's reflection or action
+      - conditions: tokens shared by every cluster member
+      - name: longest shared terms + content hash (deterministic, collision-free)
+      - evidence_ids: all member timestamps
+      - cluster_size, canonical_salience: fed into the promotion gate
+    """
+    canonical = max(cluster, key=salience_score)
+    claim = (canonical.get("reflection") or canonical.get("action") or "").strip()
+
+    feature_sets = [_entry_features(e) for e in cluster]
+    common = set.intersection(*feature_sets) if feature_sets else set()
+
+    top_terms = sorted(common, key=lambda t: (-len(t), t))[:3]
+    sig = hashlib.md5(" ".join(sorted(common)).encode()).hexdigest()[:6]
+    name_base = "_".join(top_terms) if top_terms else "untitled"
+    name = f"pattern_{name_base}_{sig}"
+
+    return {
+        "name": name,
+        "claim": claim,
+        "conditions": sorted(common),
+        "evidence_ids": [e.get("timestamp", "") for e in cluster if e.get("timestamp")],
+        "cluster_size": len(cluster),
+        "canonical_salience": salience_score(canonical),
+    }
diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index eb5a3d4..37d64e9 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -1,46 +1,72 @@
-"""Detect recurring patterns and promote high-salience entries to semantic memory."""
-import os, datetime
-from collections import defaultdict
-import sys
+"""Cluster + extract + stage candidates. No graduation here — CLI tools do that.
 
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "harness"))
-from salience import salience_score
+Pipeline:
+  1. cluster_and_extract(entries) — content clusters → structured patterns
+  2. write_candidates(patterns, dir) — patterns → candidate JSON files
 
+Every staged candidate carries lifecycle metadata (status, decisions,
+rejection_count) from birth so repeated churn is visible rather than looking
+fresh each time the pattern recurs.
+"""
+import os, json, datetime, hashlib
+from cluster import content_cluster, extract_pattern
 
-def find_recurring_patterns(entries):
-    """Cluster by (skill, action-prefix); entries appearing 2+ times get boosted."""
-    groups = defaultdict(list)
-    for e in entries:
-        key = f"{e.get('skill','general')}::{e.get('action','')[:50]}"
-        groups[key].append(e)
 
-    recurring = {}
-    for key, group in groups.items():
-        if len(group) < 2:
-            continue
-        best = max(group, key=salience_score)
-        best["recurrence_count"] = len(group)
-        best["_salience"] = salience_score(best)
-        recurring[key] = best
-    return recurring
+def cluster_and_extract(entries, threshold=0.3):
+    """Cluster entries by content similarity, extract a pattern per cluster."""
+    clusters = content_cluster(entries, threshold=threshold)
+    return {p["name"]: p for p in (extract_pattern(c) for c in clusters)}
 
 
-def promote_to_semantic(entries, semantic_dir):
-    """Append lessons that aren't already present. Returns count promoted."""
-    if not entries:
-        return 0
-    lessons_path = os.path.join(semantic_dir, "LESSONS.md")
-    existing = open(lessons_path).read() if os.path.exists(lessons_path) else ""
-    new = []
-    for e in entries:
-        line = f"- {e.get('reflection') or e.get('action') or 'unknown'}"
-        if line.strip() and line not in existing:
-            new.append(line)
-    if not new:
+def _slug(key):
+    return hashlib.md5(key.encode()).hexdigest()[:12]
+
+
+def write_candidates(patterns, candidates_dir):
+    """Stage each pattern as a candidate JSON with initial lifecycle metadata.
+
+    Idempotent per pattern key: re-staging preserves prior decision history
+    and rejection_count. A pattern rejected three times and re-detected a
+    fourth time still shows rejection_count=3 to the reviewer.
+    """
+    if not patterns:
         return 0
-    os.makedirs(semantic_dir, exist_ok=True)
-    with open(lessons_path, "a") as f:
-        f.write(f"\n## Auto-promoted {datetime.date.today().isoformat()}\n")
-        for line in new:
-            f.write(line + "\n")
-    return len(new)
+    os.makedirs(candidates_dir, exist_ok=True)
+    written = 0
+    for key, p in patterns.items():
+        claim = (p.get("claim") or "").strip()
+        if not claim:
+            continue
+        slug = _slug(key)
+        path = os.path.join(candidates_dir, f"{slug}.json")
+        now = datetime.datetime.now().isoformat()
+
+        prev = {}
+        if os.path.exists(path):
+            try:
+                with open(path) as f:
+                    prev = json.load(f)
+            except (OSError, json.JSONDecodeError):
+                prev = {}
+
+        decisions = prev.get("decisions", [])
+        decisions.append({"ts": now, "action": "staged", "reviewer": "auto_dream"})
+
+        candidate = {
+            "id": slug,
+            "key": key,
+            "name": p.get("name", key),
+            "claim": claim,
+            "conditions": p.get("conditions", []),
+            "evidence_ids": p.get("evidence_ids", []),
+            "cluster_size": p.get("cluster_size", 1),
+            "canonical_salience": p.get("canonical_salience", 0.0),
+            "staged_at": now,
+            "status": "staged",
+            "decisions": decisions,
+            "rejection_count": prev.get("rejection_count", 0),
+        }
+        with open(path, "w") as f:
+            json.dump(candidate, f, indent=2)
+        written += 1
+    return written
diff --git a/.agent/memory/render_lessons.py b/.agent/memory/render_lessons.py
new file mode 100644
index 0000000..0fcb71b
--- /dev/null
+++ b/.agent/memory/render_lessons.py
@@ -0,0 +1,123 @@
+"""Render semantic/LESSONS.md from structured semantic/lessons.jsonl.
+
+lessons.jsonl is the source of truth. LESSONS.md is a derived view. Graduate.py
+and reject.py write to lessons.jsonl and call render_lessons to regenerate
+the markdown.
+
+Preserves user content above the sentinel. On first call, the existing
+`## Auto-promoted entries will be appended below` line (shipped in the
+template) is treated as the sentinel; subsequent calls replace everything
+from the sentinel onward. If the sentinel is missing it's appended at the
+end of the file. This means hand-curated preambles and seed bullets above
+the sentinel survive every render.
+"""
+import os, json, datetime
+from collections import defaultdict
+
+
+LESSONS_JSONL = "lessons.jsonl"
+LESSONS_MD = "LESSONS.md"
+
+SENTINEL = "## Auto-promoted entries will be appended below"
+
+
+def append_lesson(lesson, semantic_dir):
+    """Append a lesson to semantic/lessons.jsonl. Returns the written path."""
+    os.makedirs(semantic_dir, exist_ok=True)
+    path = os.path.join(semantic_dir, LESSONS_JSONL)
+    with open(path, "a") as f:
+        f.write(json.dumps(lesson) + "\n")
+    return path
+
+
+def load_lessons(semantic_dir):
+    path = os.path.join(semantic_dir, LESSONS_JSONL)
+    if not os.path.exists(path):
+        return []
+    out = []
+    for line in open(path):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            out.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def _bullet_for(lesson, superseded_by):
+    claim = lesson.get("claim", "")
+    conf = lesson.get("confidence", "?")
+    status = lesson.get("status", "accepted")
+    ev = lesson.get("evidence_ids", [])
+    lid = lesson.get("id", "?")
+    ann = f"status={status} confidence={conf} evidence={len(ev)} id={lid}"
+    sup_by = superseded_by.get(lid)
+    if sup_by:
+        return f"- ~~{claim}~~  <!-- {ann} superseded_by={sup_by} -->"
+    if status == "provisional":
+        return f"- [PROVISIONAL] {claim}  <!-- {ann} -->"
+    return f"- {claim}  <!-- {ann} -->"
+
+
+def _build_auto_section(lessons):
+    superseded_by = {}
+    for L in lessons:
+        sup = L.get("supersedes")
+        if sup:
+            superseded_by[sup] = L.get("id")
+
+    groups = defaultdict(list)
+    for L in lessons:
+        month = (L.get("accepted_at") or "")[:7] or "unknown"
+        groups[month].append(L)
+
+    lines = []
+    for month in sorted(groups.keys(), reverse=True):
+        lines.append(f"### {month}")
+        lines.append("")
+        for L in groups[month]:
+            lines.append(_bullet_for(L, superseded_by))
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n" if lines else ""
+
+
+def render_lessons(semantic_dir):
+    """Re-render LESSONS.md. Preserves hand-curated content above the sentinel."""
+    lessons = load_lessons(semantic_dir)
+    auto_section = _build_auto_section(lessons)
+
+    path = os.path.join(semantic_dir, LESSONS_MD)
+
+    if os.path.exists(path):
+        existing = open(path).read()
+        if SENTINEL in existing:
+            prefix = existing.split(SENTINEL)[0].rstrip()
+            new = f"{prefix}\n\n{SENTINEL}\n\n{auto_section}"
+        else:
+            new = existing.rstrip() + f"\n\n{SENTINEL}\n\n{auto_section}"
+    else:
+        header = (
+            "# Lessons\n\n"
+            "> _Auto-managed below. Hand-curated preamble + seed lessons "
+            "above the sentinel are preserved across renders._\n"
+        )
+        new = f"{header}\n{SENTINEL}\n\n{auto_section}"
+
+    os.makedirs(semantic_dir, exist_ok=True)
+    with open(path, "w") as f:
+        f.write(new)
+    return path
+
+
+def render_lessons_as_text(semantic_dir):
+    return open(render_lessons(semantic_dir)).read()
+
+
+if __name__ == "__main__":
+    import sys
+    sem = sys.argv[1] if len(sys.argv) > 1 else os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "semantic")
+    path = render_lessons(sem)
+    print(f"rendered: {path}")
diff --git a/.agent/memory/review_state.py b/.agent/memory/review_state.py
new file mode 100644
index 0000000..93c3ff6
--- /dev/null
+++ b/.agent/memory/review_state.py
@@ -0,0 +1,203 @@
+"""Candidate lifecycle + decision log.
+
+Each candidate JSON under memory/candidates/ carries:
+  status:    staged | provisional | accepted | rejected | superseded
+  decisions: append-only list of {ts, action, reviewer, notes, **fields}
+
+Host-agent CLI tools (.agent/tools/graduate.py, reject.py, reopen.py) call
+into this module to transition state. Rejection and re-stage preserve full
+history so a candidate that keeps reappearing is visibly churning rather
+than looking novel each time.
+"""
+import os, json, datetime
+
+
+def _now():
+    return datetime.datetime.now().isoformat()
+
+
+def _touch(candidate, action, reviewer, notes="", **fields):
+    decisions = candidate.setdefault("decisions", [])
+    decisions.append({
+        "ts": _now(),
+        "action": action,
+        "reviewer": reviewer,
+        "notes": notes,
+        **fields,
+    })
+
+
+def load_candidate(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+def save_candidate(candidate, path):
+    with open(path, "w") as f:
+        json.dump(candidate, f, indent=2)
+
+
+def stage_candidate(candidate_path, reviewer="auto_dream"):
+    """Mark a freshly-written candidate as staged with an initial decision entry."""
+    cand = load_candidate(candidate_path)
+    cand.setdefault("status", "staged")
+    _touch(cand, "staged", reviewer)
+    save_candidate(cand, candidate_path)
+
+
+def mark_graduated(candidate_id, reviewer, rationale, candidates_dir,
+                   provisional=False):
+    """Move a staged candidate to candidates/graduated/ with an accept decision.
+
+    Returns the graduated candidate dict. Caller is responsible for writing
+    the structured lesson entry to semantic/lessons.jsonl and re-rendering
+    LESSONS.md — this function only handles the candidate side.
+    """
+    src = os.path.join(candidates_dir, f"{candidate_id}.json")
+    if not os.path.exists(src):
+        raise FileNotFoundError(f"candidate not found: {candidate_id}")
+    cand = load_candidate(src)
+    cand["status"] = "provisional" if provisional else "accepted"
+    cand["accepted_at"] = _now()
+    cand["reviewer"] = reviewer
+    cand["rationale"] = rationale
+    _touch(cand, "graduated", reviewer, notes=rationale,
+           provisional=provisional)
+
+    graduated_dir = os.path.join(candidates_dir, "graduated")
+    os.makedirs(graduated_dir, exist_ok=True)
+    dst = os.path.join(graduated_dir, f"{candidate_id}.json")
+    save_candidate(cand, dst)
+    os.remove(src)
+    return cand
+
+
+def mark_rejected(candidate_id, reviewer, reason, candidates_dir):
+    """Move a staged candidate to candidates/rejected/ with a reject decision.
+
+    rejection_count tracks how many times this id has been rejected — if it
+    keeps coming back, the reviewer sees churn instead of a 'fresh' item.
+    """
+    src = os.path.join(candidates_dir, f"{candidate_id}.json")
+    if not os.path.exists(src):
+        raise FileNotFoundError(f"candidate not found: {candidate_id}")
+    cand = load_candidate(src)
+    cand["status"] = "rejected"
+    cand["rejection_count"] = cand.get("rejection_count", 0) + 1
+    _touch(cand, "rejected", reviewer, notes=reason)
+
+    rejected_dir = os.path.join(candidates_dir, "rejected")
+    os.makedirs(rejected_dir, exist_ok=True)
+    dst = os.path.join(rejected_dir, f"{candidate_id}.json")
+    save_candidate(cand, dst)
+    os.remove(src)
+    return cand
+
+
+def mark_reopened(candidate_id, reviewer, candidates_dir):
+    """Move a rejected candidate back to the staged pool with history intact."""
+    src = os.path.join(candidates_dir, "rejected", f"{candidate_id}.json")
+    if not os.path.exists(src):
+        raise FileNotFoundError(f"rejected candidate not found: {candidate_id}")
+    cand = load_candidate(src)
+    cand["status"] = "staged"
+    _touch(cand, "reopened", reviewer)
+
+    dst = os.path.join(candidates_dir, f"{candidate_id}.json")
+    save_candidate(cand, dst)
+    os.remove(src)
+    return cand
+
+
+def _age_factor(staged_at):
+    """1.0 at stage time, grows to 2.0 for candidates ~14 days old."""
+    try:
+        staged = datetime.datetime.fromisoformat(staged_at)
+    except (ValueError, TypeError):
+        return 1.0
+    age_days = (datetime.datetime.now() - staged).days
+    return 1.0 + min(1.0, age_days / 14.0)
+
+
+def candidate_priority(candidate):
+    """priority = cluster_size * canonical_salience * age_factor.
+
+    Reviewers attack high-priority items first. Older + more-recurrent +
+    higher-salience patterns deserve attention ahead of one-offs.
+    """
+    return (
+        max(1, candidate.get("cluster_size", 1)) *
+        max(0.1, candidate.get("canonical_salience", 0.1)) *
+        _age_factor(candidate.get("staged_at", ""))
+    )
+
+
+def list_candidates(candidates_dir, status="staged", sort_by="priority"):
+    """Return candidate dicts with the given status, sorted by the key."""
+    if status == "staged":
+        search_dir = candidates_dir
+    else:
+        search_dir = os.path.join(candidates_dir, status)
+    if not os.path.isdir(search_dir):
+        return []
+
+    out = []
+    for fname in os.listdir(search_dir):
+        if not fname.endswith(".json"):
+            continue
+        path = os.path.join(search_dir, fname)
+        if not os.path.isfile(path):
+            continue
+        try:
+            with open(path) as f:
+                out.append(json.load(f))
+        except (OSError, json.JSONDecodeError):
+            continue
+
+    if sort_by == "priority":
+        out.sort(key=candidate_priority, reverse=True)
+    elif sort_by == "age":
+        out.sort(key=lambda c: c.get("staged_at", ""))
+    return out
+
+
+def write_review_queue_summary(candidates_dir, summary_path):
+    """Emit a compact REVIEW_QUEUE.md so the host agent sees the backlog.
+
+    On-demand review without a surfacing mechanism grows silent backlog.
+    This file sits in memory/working/ and gets loaded by context_budget into
+    every host session — impossible to miss.
+    """
+    pending = list_candidates(candidates_dir, status="staged")
+    os.makedirs(os.path.dirname(summary_path), exist_ok=True)
+    if not pending:
+        with open(summary_path, "w") as f:
+            f.write("# Review Queue\n\n_No pending candidates._\n")
+        return 0
+
+    staged_ats = [c.get("staged_at", "") for c in pending if c.get("staged_at")]
+    oldest = min(staged_ats) if staged_ats else ""
+    lines = ["# Review Queue", ""]
+    lines.append(f"**Pending:** {len(pending)}")
+    if oldest:
+        lines.append(f"**Oldest staged:** {oldest}")
+    lines.append("")
+    lines.append("Run `python .agent/tools/list_candidates.py` for detail, then:")
+    lines.append("- `python .agent/tools/graduate.py <id> --rationale \"...\"` to accept")
+    lines.append("- `python .agent/tools/reject.py <id> --reason \"...\"` to reject")
+    lines.append("- Review in a batch so cross-candidate contradictions are caught.")
+    lines.append("")
+    lines.append("## Priority order (top 10)")
+    lines.append("")
+    for cand in pending[:10]:
+        prio = candidate_priority(cand)
+        claim_preview = (cand.get("claim") or "")[:80]
+        lines.append(
+            f"- **{cand.get('id')}** (priority={prio:.2f}, "
+            f"size={cand.get('cluster_size', '?')}, "
+            f"rejections={cand.get('rejection_count', 0)}) "
+            f"— {claim_preview}"
+        )
+    with open(summary_path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+    return len(pending)
diff --git a/.agent/memory/validate.py b/.agent/memory/validate.py
new file mode 100644
index 0000000..c0d8f7e
--- /dev/null
+++ b/.agent/memory/validate.py
@@ -0,0 +1,79 @@
+"""Heuristic pre-filter for candidate lessons. Deterministic, no LLM.
+
+The host agent (Claude Code, Codex, Windsurf) does actual reasoning via the
+CLI tools in .agent/tools/ (graduate.py, reject.py). This module catches
+obvious junk — too-short claims, exact duplicates — before the reviewer
+sees the candidate at all. Anything subjective is the host's job.
+"""
+import re
+
+MIN_CLAIM_LEN = 20
+LENGTH_SATURATE = 100
+CLUSTER_SATURATE = 5
+
+
+def _normalize(text):
+    """Lowercase, strip punctuation, collapse whitespace. For exact-dup detection."""
+    t = re.sub(r"[^\w\s]", " ", (text or "").lower())
+    return re.sub(r"\s+", " ", t).strip()
+
+
+def _extract_lesson_lines(lessons_md):
+    out = []
+    for line in (lessons_md or "").splitlines():
+        s = line.strip()
+        if s.startswith("- ") and len(s) > 2:
+            out.append(s[2:].split("<!--")[0].strip())
+    return [l for l in out if l]
+
+
+def check_exact_duplicate(claim, existing_lessons_md):
+    """Return lesson lines whose normalized form matches the candidate."""
+    nc = _normalize(claim)
+    if not nc:
+        return []
+    return [l for l in _extract_lesson_lines(existing_lessons_md)
+            if _normalize(l) == nc]
+
+
+def heuristic_check(candidate, existing_lessons_md=""):
+    """Deterministic pre-filter. Takes a candidate dict, not a claim string.
+
+    passed=False means obvious junk: too short, or exact duplicate of a
+    lesson already in LESSONS.md. Everything else should reach the host
+    agent for real review — overlap != contradiction.
+
+    Returns {passed, confidence, reasons, duplicates}.
+      confidence — structural quality hint for reviewer priority only, not a gate.
+    """
+    claim = (candidate.get("claim") or "").strip()
+    reasons, duplicates = [], []
+
+    if len(claim) < MIN_CLAIM_LEN:
+        reasons.append("claim_too_short")
+
+    if claim:
+        duplicates = check_exact_duplicate(claim, existing_lessons_md)
+        if duplicates:
+            reasons.append(f"exact_duplicate_of_{len(duplicates)}_lessons")
+
+    cluster_size = candidate.get("cluster_size", 1)
+    length_score = min(1.0, len(claim) / LENGTH_SATURATE)
+    size_score = min(1.0, cluster_size / CLUSTER_SATURATE)
+    confidence = round(0.5 * length_score + 0.5 * size_score, 3)
+
+    return {
+        "passed": not reasons,
+        "confidence": confidence,
+        "reasons": reasons,
+        "duplicates": duplicates,
+    }
+
+
+def validate_candidate(claim_or_candidate, existing_lessons_md="", bootstrap=False):
+    """Backwards-compat shim. Old callers passed a claim string; new callers
+    pass a candidate dict. bootstrap is accepted but ignored — heuristic
+    check has no threshold to loosen."""
+    if isinstance(claim_or_candidate, str):
+        return heuristic_check({"claim": claim_or_candidate}, existing_lessons_md)
+    return heuristic_check(claim_or_candidate, existing_lessons_md)
diff --git a/.agent/tools/graduate.py b/.agent/tools/graduate.py
new file mode 100644
index 0000000..7b05fea
--- /dev/null
+++ b/.agent/tools/graduate.py
@@ -0,0 +1,84 @@
+"""Graduate a staged candidate to semantic memory.
+
+The host agent reviews a candidate, decides it's worth keeping, and calls
+this tool with a rationale. A heuristic re-check (length + exact duplicate
+against current LESSONS.md) runs automatically so last-minute issues get
+caught. The rationale is REQUIRED — rubber-stamped promotions are the
+whole failure mode this layer is designed to prevent.
+"""
+import os, sys, json, argparse, hashlib
+
+BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(BASE, "memory"))
+
+from review_state import mark_graduated
+from validate import heuristic_check
+from render_lessons import append_lesson, render_lessons
+
+CANDIDATES = os.path.join(BASE, "memory/candidates")
+SEMANTIC = os.path.join(BASE, "memory/semantic")
+
+
+def _lesson_id(candidate):
+    claim = (candidate.get("claim") or "").strip().lower()
+    return "lesson_" + hashlib.md5(claim.encode()).hexdigest()[:12]
+
+
+def main():
+    p = argparse.ArgumentParser(description="Graduate a staged candidate.")
+    p.add_argument("candidate_id")
+    p.add_argument("--rationale", required=True,
+                   help="Why this lesson should be accepted. Required, not optional.")
+    p.add_argument("--reviewer", default="host-agent")
+    p.add_argument("--provisional", action="store_true",
+                   help="Accept as provisional (probationary) rather than full.")
+    p.add_argument("--supersedes", default=None,
+                   help="ID of an existing lesson this replaces.")
+    args = p.parse_args()
+
+    cand_path = os.path.join(CANDIDATES, f"{args.candidate_id}.json")
+    if not os.path.exists(cand_path):
+        print(f"ERROR: candidate not found: {args.candidate_id}", file=sys.stderr)
+        sys.exit(1)
+    with open(cand_path) as f:
+        cand = json.load(f)
+
+    lessons_md = os.path.join(SEMANTIC, "LESSONS.md")
+    existing = open(lessons_md).read() if os.path.exists(lessons_md) else ""
+    check = heuristic_check(cand, existing)
+    if not check["passed"]:
+        print(f"ERROR: candidate fails heuristic check: {check['reasons']}",
+              file=sys.stderr)
+        sys.exit(2)
+
+    graduated = mark_graduated(
+        args.candidate_id, args.reviewer, args.rationale, CANDIDATES,
+        provisional=args.provisional,
+    )
+
+    lesson = {
+        "id": _lesson_id(cand),
+        "claim": cand.get("claim"),
+        "conditions": cand.get("conditions", []),
+        "evidence_ids": cand.get("evidence_ids", []),
+        "status": "provisional" if args.provisional else "accepted",
+        "accepted_at": graduated.get("accepted_at"),
+        "reviewer": args.reviewer,
+        "rationale": args.rationale,
+        "cluster_size": cand.get("cluster_size", 1),
+        "canonical_salience": cand.get("canonical_salience", 0.0),
+        "confidence": check["confidence"],
+        "support_count": 0,
+        "contradiction_count": 0,
+        "supersedes": args.supersedes,
+        "source_candidate": args.candidate_id,
+    }
+    append_lesson(lesson, SEMANTIC)
+    md_path = render_lessons(SEMANTIC)
+
+    print(f"graduated {args.candidate_id} → lesson {lesson['id']}")
+    print(f"re-rendered: {md_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.agent/tools/list_candidates.py b/.agent/tools/list_candidates.py
new file mode 100644
index 0000000..82c67fd
--- /dev/null
+++ b/.agent/tools/list_candidates.py
@@ -0,0 +1,62 @@
+"""List candidate lessons by status + priority.
+
+Host-agent workflow: run this, pick the top N, review each with graduate.py
+or reject.py. Priority = cluster_size * canonical_salience * age_factor, so
+recurring + salient + aging items get attention first.
+"""
+import os, sys, json, argparse
+
+BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(BASE, "memory"))
+
+from review_state import list_candidates, candidate_priority
+
+CANDIDATES = os.path.join(BASE, "memory/candidates")
+
+
+def main():
+    p = argparse.ArgumentParser(description="List candidate lessons.")
+    p.add_argument("--status", default="staged",
+                   choices=["staged", "rejected", "graduated"])
+    p.add_argument("--sort", default="priority",
+                   choices=["priority", "age"])
+    p.add_argument("--limit", type=int, default=0,
+                   help="Max to return; 0 = no limit.")
+    p.add_argument("--format", default="human", choices=["human", "json"])
+    args = p.parse_args()
+
+    items = list_candidates(CANDIDATES, status=args.status, sort_by=args.sort)
+    if args.limit:
+        items = items[:args.limit]
+
+    if args.format == "json":
+        print(json.dumps(
+            [{**c, "priority": round(candidate_priority(c), 3)} for c in items],
+            indent=2))
+        return
+
+    if not items:
+        print(f"No candidates with status={args.status}.")
+        return
+
+    print(f"=== {len(items)} candidate(s) — status={args.status} ===\n")
+    for c in items:
+        prio = candidate_priority(c)
+        print(f"# {c.get('id')}  (priority={prio:.2f})")
+        print(f"  claim:      {c.get('claim', '')}")
+        print(f"  cluster:    {c.get('cluster_size', '?')} episode(s)")
+        print(f"  salience:   {c.get('canonical_salience', 0):.2f}")
+        print(f"  conditions: {c.get('conditions', [])}")
+        print(f"  evidence:   {len(c.get('evidence_ids', []))} episode(s)")
+        print(f"  rejections: {c.get('rejection_count', 0)}")
+        print(f"  staged:     {c.get('staged_at', '?')}")
+        dec = c.get("decisions", [])
+        if dec:
+            last = dec[-1]
+            print(f"  last:       {last.get('action')} by "
+                  f"{last.get('reviewer')} @ {last.get('ts', '')[:19]}")
+        print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.agent/tools/memory_reflect.py b/.agent/tools/memory_reflect.py
index bb88e98..7101bb0 100644
--- a/.agent/tools/memory_reflect.py
+++ b/.agent/tools/memory_reflect.py
@@ -7,12 +7,16 @@
 
 
 def reflect(skill_name, action, outcome, success=True, importance=5,
-            reflection="", error=None):
+            reflection="", error=None, confidence=None, evidence_ids=None):
     if success:
         return log_execution(skill_name, action, outcome, True,
-                             reflection=reflection, importance=importance)
+                             reflection=reflection, importance=importance,
+                             confidence=0.5 if confidence is None else confidence,
+                             evidence_ids=evidence_ids)
     return on_failure(skill_name, action, error or outcome,
-                      context=reflection)
+                      context=reflection,
+                      confidence=0.9 if confidence is None else confidence,
+                      evidence_ids=evidence_ids)
 
 
 if __name__ == "__main__":
@@ -24,7 +28,11 @@ def reflect(skill_name, action, outcome, success=True, importance=5,
     p.add_argument("--fail", action="store_true")
     p.add_argument("--importance", type=int, default=5)
     p.add_argument("--note", default="")
+    p.add_argument("--confidence", type=float, default=None)
+    p.add_argument("--evidence", nargs="*", default=None,
+                   help="Space-separated episode/lesson IDs this entry builds on.")
     args = p.parse_args()
     print(reflect(args.skill, args.action, args.outcome,
                   success=not args.fail, importance=args.importance,
-                  reflection=args.note))
+                  reflection=args.note, confidence=args.confidence,
+                  evidence_ids=args.evidence))
diff --git a/.agent/tools/reject.py b/.agent/tools/reject.py
new file mode 100644
index 0000000..2567807
--- /dev/null
+++ b/.agent/tools/reject.py
@@ -0,0 +1,38 @@
+"""Reject a staged candidate. Moves to rejected/ with a decision log entry.
+
+The candidate is not deleted. Its decision history, including the reject
+reason, is preserved. If the same pattern recurs and gets re-staged by
+auto_dream, rejection_count will show the history — so the reviewer sees
+churn instead of treating it as a fresh item.
+"""
+import os, sys, argparse
+
+BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(BASE, "memory"))
+
+from review_state import mark_rejected
+
+CANDIDATES = os.path.join(BASE, "memory/candidates")
+
+
+def main():
+    p = argparse.ArgumentParser(description="Reject a staged candidate.")
+    p.add_argument("candidate_id")
+    p.add_argument("--reason", required=True,
+                   help="Why it's being rejected. Required.")
+    p.add_argument("--reviewer", default="host-agent")
+    args = p.parse_args()
+
+    try:
+        rejected = mark_rejected(args.candidate_id, args.reviewer,
+                                 args.reason, CANDIDATES)
+    except FileNotFoundError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"rejected {args.candidate_id} "
+          f"(rejection_count={rejected.get('rejection_count', 1)})")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.agent/tools/reopen.py b/.agent/tools/reopen.py
new file mode 100644
index 0000000..3375dd7
--- /dev/null
+++ b/.agent/tools/reopen.py
@@ -0,0 +1,34 @@
+"""Move a rejected candidate back to the staged pool.
+
+Use this when a previous rejection was wrong, or when new evidence changes
+the picture. Decision history and rejection_count survive the reopen — the
+next reviewer sees the full churn log.
+"""
+import os, sys, argparse
+
+BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, os.path.join(BASE, "memory"))
+
+from review_state import mark_reopened
+
+CANDIDATES = os.path.join(BASE, "memory/candidates")
+
+
+def main():
+    p = argparse.ArgumentParser(description="Reopen a rejected candidate.")
+    p.add_argument("candidate_id")
+    p.add_argument("--reviewer", default="host-agent")
+    args = p.parse_args()
+
+    try:
+        cand = mark_reopened(args.candidate_id, args.reviewer, CANDIDATES)
+    except FileNotFoundError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"reopened {args.candidate_id} "
+          f"(rejection_count={cand.get('rejection_count', 0)})")
+
+
+if __name__ == "__main__":
+    main()

From f84acc515eace2e7a5eeaa52df4ed42d5e7c998d Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 02:49:26 +0530
Subject: [PATCH 02/10] fix(.agent): address codex review findings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P1] write_candidates now looks up prior state across all lifecycle
  subdirs (staged/rejected/graduated), not just the staged location.
  A rejected candidate re-detected by clustering is moved back to
  staged with rejection_count and decision log preserved; the stale
  rejected/<slug>.json is removed so the id never exists in two
  states at once. A graduated candidate is skipped entirely — the
  lesson already lives in lessons.jsonl.

- [P2] staged_at is preserved across re-staging. candidate_priority()
  and the "oldest staged" backlog signal in REVIEW_QUEUE.md both
  depend on staged_at representing the true first-staged time;
  overwriting it to now() made recurring candidates never age and
  stop surfacing as stale work.

- [P2] run_dream_cycle now refreshes REVIEW_QUEUE.md even when the
  episodic log is empty. build_context loads the queue into every
  host session, so a stale/missing file silently hides pending
  review items. The early-return path now writes the queue first
  and reports pending count in its log line.

Smoke tests verify:
- rejected → re-detected: rejection_count=1, staged_at preserved,
  decisions log shows [staged, rejected, staged], old rejected/
  copy cleared.
- graduated → re-detected: write_candidates returns 0 (skipped);
  graduated/ file intact.
- empty episodic with prior pending: REVIEW_QUEUE.md regenerated
  with correct Pending count + Oldest staged timestamp.
---
 .agent/memory/auto_dream.py |  6 +++-
 .agent/memory/promote.py    | 72 +++++++++++++++++++++++++++++--------
 2 files changed, 62 insertions(+), 16 deletions(-)

diff --git a/.agent/memory/auto_dream.py b/.agent/memory/auto_dream.py
index 8d5f3d7..e1eb2eb 100644
--- a/.agent/memory/auto_dream.py
+++ b/.agent/memory/auto_dream.py
@@ -83,7 +83,11 @@ def _heuristic_prefilter(candidates_dir, semantic_dir):
 def run_dream_cycle():
     entries = _load_entries()
     if not entries:
-        print("dream cycle: no entries")
+        # Still refresh the review queue — candidates may have been staged in
+        # a previous cycle and the host agent loads REVIEW_QUEUE.md into every
+        # session via build_context, so a stale/missing file hides real work.
+        pending = write_review_queue_summary(CANDIDATES, REVIEW_QUEUE)
+        print(f"dream cycle: no entries (queue has {pending} pending)")
         return
 
     patterns = cluster_and_extract(entries, threshold=CLUSTER_SIMILARITY)
diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index 37d64e9..1d642e4 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -22,12 +22,44 @@ def _slug(key):
     return hashlib.md5(key.encode()).hexdigest()[:12]
 
 
+def _find_prior(slug, candidates_dir):
+    """Look up any prior record for this slug across lifecycle subdirs.
+
+    Returns (prev_dict, location) where location is one of
+    'staged' | 'rejected' | 'graduated' | None. A slug can only live in
+    one place at a time; the caller is responsible for cleaning up the
+    old location when moving the candidate back to staged.
+    """
+    staged_path = os.path.join(candidates_dir, f"{slug}.json")
+    if os.path.isfile(staged_path):
+        try:
+            with open(staged_path) as f:
+                return json.load(f), "staged"
+        except (OSError, json.JSONDecodeError):
+            pass
+    for sub in ("rejected", "graduated"):
+        path = os.path.join(candidates_dir, sub, f"{slug}.json")
+        if os.path.isfile(path):
+            try:
+                with open(path) as f:
+                    return json.load(f), sub
+            except (OSError, json.JSONDecodeError):
+                pass
+    return {}, None
+
+
 def write_candidates(patterns, candidates_dir):
-    """Stage each pattern as a candidate JSON with initial lifecycle metadata.
+    """Stage each pattern as a candidate JSON with lifecycle metadata.
 
-    Idempotent per pattern key: re-staging preserves prior decision history
-    and rejection_count. A pattern rejected three times and re-detected a
-    fourth time still shows rejection_count=3 to the reviewer.
+    Checks all three lifecycle subdirs (staged / rejected / graduated) for an
+    existing record with the same slug, and preserves its history.
+      - staged already: append a new 'staged' decision, keep original staged_at.
+      - rejected previously: move back to staged with rejection_count and
+        decision log intact. The reviewer sees this as a recurring pattern,
+        not a fresh one.
+      - graduated previously: skip entirely. The lesson already lives in
+        lessons.jsonl; re-staging would only create work the heuristic
+        prefilter would then reject on exact-duplicate grounds.
     """
     if not patterns:
         return 0
@@ -38,20 +70,20 @@ def write_candidates(patterns, candidates_dir):
         if not claim:
             continue
         slug = _slug(key)
-        path = os.path.join(candidates_dir, f"{slug}.json")
-        now = datetime.datetime.now().isoformat()
+        prev, prev_loc = _find_prior(slug, candidates_dir)
 
-        prev = {}
-        if os.path.exists(path):
-            try:
-                with open(path) as f:
-                    prev = json.load(f)
-            except (OSError, json.JSONDecodeError):
-                prev = {}
+        # Already accepted upstream — don't resurrect as a candidate.
+        if prev_loc == "graduated":
+            continue
 
+        now = datetime.datetime.now().isoformat()
         decisions = prev.get("decisions", [])
         decisions.append({"ts": now, "action": "staged", "reviewer": "auto_dream"})
 
+        # Preserve original staged_at so priority + backlog age signals stay
+        # meaningful across re-detections.
+        staged_at = prev.get("staged_at") or now
+
         candidate = {
             "id": slug,
             "key": key,
@@ -61,12 +93,22 @@ def write_candidates(patterns, candidates_dir):
             "evidence_ids": p.get("evidence_ids", []),
             "cluster_size": p.get("cluster_size", 1),
             "canonical_salience": p.get("canonical_salience", 0.0),
-            "staged_at": now,
+            "staged_at": staged_at,
             "status": "staged",
             "decisions": decisions,
             "rejection_count": prev.get("rejection_count", 0),
         }
-        with open(path, "w") as f:
+
+        staged_path = os.path.join(candidates_dir, f"{slug}.json")
+        with open(staged_path, "w") as f:
             json.dump(candidate, f, indent=2)
+
+        # If the candidate was previously rejected, remove it from the
+        # rejected subdir so the same id isn't tracked in two states at once.
+        if prev_loc == "rejected":
+            try:
+                os.remove(os.path.join(candidates_dir, "rejected", f"{slug}.json"))
+            except OSError:
+                pass
         written += 1
     return written

From 59c78e8476632d2562bca9ad3f55bdc48c22ad3b Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 03:11:47 +0530
Subject: [PATCH 03/10] fix(.agent): address second codex review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P1] render_lessons now migrates legacy auto-promoted bullets below
  the sentinel into lessons.jsonl on first run. Without this, an
  installation upgrading from the old markdown-only format would have
  its previously-promoted lessons silently erased the first time
  graduate.py (or any path that calls render_lessons) ran with an
  empty lessons.jsonl. Migrated entries land with status='legacy'.
  Idempotent: subsequent renders don't re-import the same bullet.

- [P2] extract_pattern now boosts canonical_salience by cluster_size
  via salience_score's existing recurrence multiplier (capped at 3).
  Previously canonical_salience was computed from a single episode
  and ignored recurrence, so a cluster of 2 entries with pain=7
  importance=7 scored 4.9 and failed the 7.0 promotion threshold.
  Now scores 9.8 — matching the old recurrence-aware behavior.
  Repetition is the learning signal the pipeline is designed around.

- [P2] _extract_lesson_lines now strips the `[PROVISIONAL]` prefix
  (and `~~strikethrough~~` markers for superseded lessons) before
  returning claim text for duplicate detection. Previously a
  candidate with claim "foo" would not match an existing
  "[PROVISIONAL] foo" line, so the same provisional lesson could
  be graduated repeatedly under new candidate ids.
---
 .agent/memory/cluster.py        | 14 +++++-
 .agent/memory/render_lessons.py | 76 ++++++++++++++++++++++++++++++++-
 .agent/memory/validate.py       | 21 +++++++--
 3 files changed, 104 insertions(+), 7 deletions(-)

diff --git a/.agent/memory/cluster.py b/.agent/memory/cluster.py
index 472f964..6a807db 100644
--- a/.agent/memory/cluster.py
+++ b/.agent/memory/cluster.py
@@ -59,7 +59,11 @@ def extract_pattern(cluster):
       - conditions: tokens shared by every cluster member
       - name: longest shared terms + content hash (deterministic, collision-free)
       - evidence_ids: all member timestamps
-      - cluster_size, canonical_salience: fed into the promotion gate
+      - cluster_size: recurrence count
+      - canonical_salience: salience of the canonical episode *boosted by*
+        cluster_size. Repetition is a learning signal; a recurring-but-moderate
+        pattern must be able to clear the promotion threshold even when no
+        single episode was extreme. salience_score already caps recurrence at 3.
     """
     canonical = max(cluster, key=salience_score)
     claim = (canonical.get("reflection") or canonical.get("action") or "").strip()
@@ -72,11 +76,17 @@ def extract_pattern(cluster):
     name_base = "_".join(top_terms) if top_terms else "untitled"
     name = f"pattern_{name_base}_{sig}"
 
+    # Recurrence-aware salience: give the scoring function cluster context
+    # without mutating the source episode dict.
+    canonical_with_recurrence = dict(canonical)
+    canonical_with_recurrence["recurrence_count"] = len(cluster)
+    canonical_salience = salience_score(canonical_with_recurrence)
+
     return {
         "name": name,
         "claim": claim,
         "conditions": sorted(common),
         "evidence_ids": [e.get("timestamp", "") for e in cluster if e.get("timestamp")],
         "cluster_size": len(cluster),
-        "canonical_salience": salience_score(canonical),
+        "canonical_salience": canonical_salience,
     }
diff --git a/.agent/memory/render_lessons.py b/.agent/memory/render_lessons.py
index 0fcb71b..cc2ac69 100644
--- a/.agent/memory/render_lessons.py
+++ b/.agent/memory/render_lessons.py
@@ -11,7 +11,7 @@
 end of the file. This means hand-curated preambles and seed bullets above
 the sentinel survive every render.
 """
-import os, json, datetime
+import os, json, datetime, hashlib
 from collections import defaultdict
 
 
@@ -83,8 +83,80 @@ def _build_auto_section(lessons):
     return "\n".join(lines).rstrip() + "\n" if lines else ""
 
 
+def migrate_legacy_bullets(semantic_dir):
+    """Import any bullets below the sentinel not yet in lessons.jsonl.
+
+    Upgrade safety: installations that ran the old markdown-only promotion
+    have auto-promoted bullets below the sentinel. Without this pass, the
+    first call to render_lessons with an empty lessons.jsonl would rewrite
+    LESSONS.md with an empty auto-section and lose all of them silently.
+    Migrated entries land with status='legacy' so they're visually distinct
+    and can be reviewed + superseded by the host agent later.
+    """
+    md_path = os.path.join(semantic_dir, LESSONS_MD)
+    if not os.path.exists(md_path):
+        return 0
+    content = open(md_path).read()
+    if SENTINEL not in content:
+        return 0
+
+    below = content.split(SENTINEL, 1)[1]
+    bullets = []
+    for line in below.splitlines():
+        s = line.strip()
+        if not s.startswith("- ") or len(s) <= 2:
+            continue
+        text = s[2:].split("<!--")[0].strip()
+        # Skip superseded entries — they're historical, not content to re-ingest
+        if text.startswith("~~") and text.endswith("~~"):
+            continue
+        # Strip provisional prefix if present
+        if text.startswith("[PROVISIONAL]"):
+            text = text[len("[PROVISIONAL]"):].strip()
+        if text:
+            bullets.append(text)
+
+    if not bullets:
+        return 0
+
+    existing_claims = {(L.get("claim") or "").strip().lower()
+                       for L in load_lessons(semantic_dir)}
+    try:
+        accepted_at = datetime.datetime.fromtimestamp(
+            os.path.getmtime(md_path)).isoformat()
+    except OSError:
+        accepted_at = datetime.datetime.now().isoformat()
+
+    migrated = 0
+    for claim in bullets:
+        if claim.strip().lower() in existing_claims:
+            continue
+        lid = "lesson_legacy_" + hashlib.md5(claim.lower().encode()).hexdigest()[:12]
+        lesson = {
+            "id": lid, "claim": claim,
+            "conditions": [], "evidence_ids": [],
+            "status": "legacy", "accepted_at": accepted_at,
+            "reviewer": "render_lessons_migration",
+            "rationale": "Imported from pre-restructure LESSONS.md bullets below sentinel",
+            "cluster_size": 1, "canonical_salience": 5.0,
+            "confidence": 0.7, "support_count": 0, "contradiction_count": 0,
+            "supersedes": None, "source_candidate": None,
+        }
+        append_lesson(lesson, semantic_dir)
+        existing_claims.add(claim.strip().lower())
+        migrated += 1
+    return migrated
+
+
 def render_lessons(semantic_dir):
-    """Re-render LESSONS.md. Preserves hand-curated content above the sentinel."""
+    """Re-render LESSONS.md. Preserves hand-curated content above the sentinel.
+
+    Auto-migrates legacy auto-promoted bullets below the sentinel into
+    lessons.jsonl before rendering, so upgrades from the old markdown-only
+    format don't silently erase past promotions.
+    """
+    # First, absorb any un-registered bullets below the sentinel
+    migrate_legacy_bullets(semantic_dir)
     lessons = load_lessons(semantic_dir)
     auto_section = _build_auto_section(lessons)
 
diff --git a/.agent/memory/validate.py b/.agent/memory/validate.py
index c0d8f7e..6260acc 100644
--- a/.agent/memory/validate.py
+++ b/.agent/memory/validate.py
@@ -19,12 +19,27 @@ def _normalize(text):
 
 
 def _extract_lesson_lines(lessons_md):
+    """Extract lesson claim text from rendered markdown.
+
+    Strips render-only decorations so the duplicate check compares raw claims:
+      - HTML comment annotations (`<!-- ... -->`)
+      - `[PROVISIONAL]` prefix added by the renderer
+      - Strikethrough markers on superseded lessons (but the text is still
+        returned — a superseded lesson's claim can legitimately reappear)
+    """
     out = []
     for line in (lessons_md or "").splitlines():
         s = line.strip()
-        if s.startswith("- ") and len(s) > 2:
-            out.append(s[2:].split("<!--")[0].strip())
-    return [l for l in out if l]
+        if not s.startswith("- ") or len(s) <= 2:
+            continue
+        text = s[2:].split("<!--")[0].strip()
+        if text.startswith("[PROVISIONAL]"):
+            text = text[len("[PROVISIONAL]"):].strip()
+        if text.startswith("~~") and text.endswith("~~") and len(text) >= 4:
+            text = text[2:-2].strip()
+        if text:
+            out.append(text)
+    return out
 
 
 def check_exact_duplicate(claim, existing_lessons_md):

From 95d5e2dd034443b9c2447bf901eacbdeb2721b4f Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 03:25:33 +0530
Subject: [PATCH 04/10] fix(.agent): address third codex review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P2] write_candidates now distinguishes accepted vs provisional in
  the graduated/ subdir. Fully accepted lessons stay terminal (the
  pattern will never be re-surfaced as a candidate), but provisional
  ones are probationary by design — if the same pattern recurs, the
  host agent should see it again for evidence accumulation or
  supersession. Previously any slug in graduated/ was skipped
  regardless of status, making the provisional workflow terminal.

- [P2] review_state.mark_graduated / mark_rejected / mark_reopened
  now call write_review_queue_summary on the standard working/
  path after every transition. build_context loads the queue into
  every host session; without this refresh, a manual graduate.py
  would leave the reviewed item showing as pending until the next
  dream cycle. Uses a convention-based default path derived from
  candidates_dir, so callers don't need to pass it explicitly.

- [P3] write_candidates now skips re-staging of rejected candidates
  whose last decision was by reviewer "heuristic_prefilter". Those
  rejections are deterministic (length / exact duplicate vs
  LESSONS.md), so re-staging them every dream cycle just to have
  the prefilter reject them again does nothing but churn
  rejection_count. Human rejections still re-surface — the
  recurrence IS the signal the reviewer wants to see.
---
 .agent/memory/promote.py      | 16 ++++++++++++++--
 .agent/memory/review_state.py | 23 +++++++++++++++++++++++
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index 1d642e4..61c9e07 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -72,10 +72,22 @@ def write_candidates(patterns, candidates_dir):
         slug = _slug(key)
         prev, prev_loc = _find_prior(slug, candidates_dir)
 
-        # Already accepted upstream — don't resurrect as a candidate.
-        if prev_loc == "graduated":
+        # Fully-accepted lesson — don't resurrect. Provisional acceptance is
+        # probationary, so recurring provisional patterns SHOULD reappear
+        # for re-review + evidence accumulation.
+        if prev_loc == "graduated" and prev.get("status") != "provisional":
             continue
 
+        # Heuristic-rejected candidates (length / exact-duplicate of an
+        # existing lesson) are terminal unless a human reopens them. Without
+        # this guard, each dream cycle would re-stage the same slug and
+        # heuristic_prefilter would immediately reject it again, bumping
+        # rejection_count forever for no new signal.
+        if prev_loc == "rejected":
+            last = (prev.get("decisions") or [])[-1] if prev.get("decisions") else {}
+            if last.get("action") == "rejected" and last.get("reviewer") == "heuristic_prefilter":
+                continue
+
         now = datetime.datetime.now().isoformat()
         decisions = prev.get("decisions", [])
         decisions.append({"ts": now, "action": "staged", "reviewer": "auto_dream"})
diff --git a/.agent/memory/review_state.py b/.agent/memory/review_state.py
index 93c3ff6..2780411 100644
--- a/.agent/memory/review_state.py
+++ b/.agent/memory/review_state.py
@@ -45,6 +45,26 @@ def stage_candidate(candidate_path, reviewer="auto_dream"):
     save_candidate(cand, candidate_path)
 
 
+def _default_queue_path(candidates_dir):
+    """By convention, memory/candidates/ sits next to memory/working/REVIEW_QUEUE.md."""
+    memory_dir = os.path.dirname(candidates_dir)
+    return os.path.join(memory_dir, "working", "REVIEW_QUEUE.md")
+
+
+def _refresh_queue(candidates_dir):
+    """Keep REVIEW_QUEUE.md in sync after any lifecycle transition.
+
+    build_context loads this file into every host session, so a stale file
+    makes reviewed items keep appearing as pending and reopened items stay
+    invisible until the next dream cycle.
+    """
+    try:
+        write_review_queue_summary(candidates_dir, _default_queue_path(candidates_dir))
+    except Exception:
+        # Never let queue bookkeeping break a graduation / rejection action.
+        pass
+
+
 def mark_graduated(candidate_id, reviewer, rationale, candidates_dir,
                    provisional=False):
     """Move a staged candidate to candidates/graduated/ with an accept decision.
@@ -69,6 +89,7 @@ def mark_graduated(candidate_id, reviewer, rationale, candidates_dir,
     dst = os.path.join(graduated_dir, f"{candidate_id}.json")
     save_candidate(cand, dst)
     os.remove(src)
+    _refresh_queue(candidates_dir)
     return cand
 
 
@@ -91,6 +112,7 @@ def mark_rejected(candidate_id, reviewer, reason, candidates_dir):
     dst = os.path.join(rejected_dir, f"{candidate_id}.json")
     save_candidate(cand, dst)
     os.remove(src)
+    _refresh_queue(candidates_dir)
     return cand
 
 
@@ -106,6 +128,7 @@ def mark_reopened(candidate_id, reviewer, candidates_dir):
     dst = os.path.join(candidates_dir, f"{candidate_id}.json")
     save_candidate(cand, dst)
     os.remove(src)
+    _refresh_queue(candidates_dir)
     return cand
 
 

From c4722a65bdf508a42a128f3470058266d10b9a47 Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 03:34:56 +0530
Subject: [PATCH 05/10] fix(.agent): address fourth codex review round

The round-2 "strip [PROVISIONAL] prefix before duplicate check" fix
was defensive against a different-slug-same-claim risk. Round 4
pointed out the root cause: slugs were md5(name), and name depends
on cluster membership, so the same pattern could get a new slug
when one supporting episode joined or left. That's the actual bug
to fix; once ids are stable, the marker-stripping hack becomes
harmful (it blocks provisional lessons from ever re-entering review).

- [P2] extract_pattern now returns a stable `id` derived from
  md5(normalize(claim)). Adding or removing a supporting episode
  no longer changes the id, so lifecycle history (rejection_count,
  graduated/provisional status, decision log) carries forward.
  promote._slug prefers pattern["id"]; falls back to md5(key) for
  safety on older data.

- [P1] _extract_lesson_lines now SKIPS provisional and superseded
  lessons in the duplicate check rather than stripping their
  markers. Provisional lessons are probationary by design: a
  recurring provisional pattern must reach the host agent so
  evidence can accumulate. Superseded ("~~...~~") lessons are
  historical, not current; a new claim matching one is a
  legitimate revival.

With stable ids, the round-2 scenario (same claim under a new
slug creating a duplicate provisional) is structurally impossible,
so the marker-strip hack is no longer needed.
---
 .agent/memory/cluster.py  | 23 ++++++++++++++++++++---
 .agent/memory/promote.py  | 12 +++++++++---
 .agent/memory/validate.py | 26 ++++++++++++++++----------
 3 files changed, 45 insertions(+), 16 deletions(-)

diff --git a/.agent/memory/cluster.py b/.agent/memory/cluster.py
index 6a807db..e1992c5 100644
--- a/.agent/memory/cluster.py
+++ b/.agent/memory/cluster.py
@@ -5,13 +5,25 @@
 rather than synthesizing a new claim. Structured candidates flow through the
 Phase 1 validation gate — if no LLM is available, they defer as before.
 """
-import os, sys, hashlib
+import os, re, sys, hashlib
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "harness"))
 from text import word_set, jaccard
 from salience import salience_score
 
 
+def _normalize_claim(text):
+    """Lowercase, strip punctuation, collapse whitespace.
+
+    Used to derive a stable pattern id — same claim text must always produce
+    the same id so lifecycle state (decisions, rejection_count, graduation
+    status) carries across dream cycles even when the cluster membership
+    shifts by one episode. Kept in sync with validate._normalize.
+    """
+    t = re.sub(r"[^\w\s]", " ", (text or "").lower())
+    return re.sub(r"\s+", " ", t).strip()
+
+
 def _entry_features(entry):
     """Content feature set for clustering: action + reflection + detail."""
     text = " ".join([
@@ -72,9 +84,13 @@ def extract_pattern(cluster):
     common = set.intersection(*feature_sets) if feature_sets else set()
 
     top_terms = sorted(common, key=lambda t: (-len(t), t))[:3]
-    sig = hashlib.md5(" ".join(sorted(common)).encode()).hexdigest()[:6]
     name_base = "_".join(top_terms) if top_terms else "untitled"
-    name = f"pattern_{name_base}_{sig}"
+    # Stable id: derived from the normalized claim text, NOT cluster membership.
+    # If an extra episode joins or leaves the cluster the canonical claim is
+    # usually unchanged, so the id is unchanged, so the candidate's lifecycle
+    # history (rejection_count, graduated/provisional state) carries forward.
+    pattern_id = hashlib.md5(_normalize_claim(claim).encode()).hexdigest()[:12]
+    name = f"pattern_{name_base}_{pattern_id[:6]}"
 
     # Recurrence-aware salience: give the scoring function cluster context
     # without mutating the source episode dict.
@@ -83,6 +99,7 @@ def extract_pattern(cluster):
     canonical_salience = salience_score(canonical_with_recurrence)
 
     return {
+        "id": pattern_id,
         "name": name,
         "claim": claim,
         "conditions": sorted(common),
diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index 61c9e07..3b11c53 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -18,8 +18,12 @@ def cluster_and_extract(entries, threshold=0.3):
     return {p["name"]: p for p in (extract_pattern(c) for c in clusters)}
 
 
-def _slug(key):
-    return hashlib.md5(key.encode()).hexdigest()[:12]
+def _slug(pattern_or_key):
+    """Slug for a pattern. Prefer pattern['id'] (claim-derived, stable across
+    cluster membership changes); fall back to md5(key) for legacy callers."""
+    if isinstance(pattern_or_key, dict) and pattern_or_key.get("id"):
+        return pattern_or_key["id"]
+    return hashlib.md5(str(pattern_or_key).encode()).hexdigest()[:12]
 
 
 def _find_prior(slug, candidates_dir):
@@ -69,7 +73,9 @@ def write_candidates(patterns, candidates_dir):
         claim = (p.get("claim") or "").strip()
         if not claim:
             continue
-        slug = _slug(key)
+        # Prefer the claim-derived id from extract_pattern — stable slug
+        # means lifecycle state carries across cluster membership changes.
+        slug = _slug(p)
         prev, prev_loc = _find_prior(slug, candidates_dir)
 
         # Fully-accepted lesson — don't resurrect. Provisional acceptance is
diff --git a/.agent/memory/validate.py b/.agent/memory/validate.py
index 6260acc..d628e38 100644
--- a/.agent/memory/validate.py
+++ b/.agent/memory/validate.py
@@ -19,13 +19,19 @@ def _normalize(text):
 
 
 def _extract_lesson_lines(lessons_md):
-    """Extract lesson claim text from rendered markdown.
-
-    Strips render-only decorations so the duplicate check compares raw claims:
-      - HTML comment annotations (`<!-- ... -->`)
-      - `[PROVISIONAL]` prefix added by the renderer
-      - Strikethrough markers on superseded lessons (but the text is still
-        returned — a superseded lesson's claim can legitimately reappear)
+    """Extract accepted lesson claims from rendered markdown.
+
+    Only TERMINAL lessons count for duplicate detection:
+      - `[PROVISIONAL]` lessons are probationary; if a pattern recurs, the
+        host agent should see it for evidence accumulation or full
+        graduation. Blocking them here makes provisional an accidental
+        dead end.
+      - Strikethrough (`~~...~~`) lessons are superseded; a new claim that
+        happens to match a superseded one is a legitimate revival, not a
+        duplicate.
+    Stable candidate ids (derived from claim text in cluster.extract_pattern)
+    handle the "same claim under different slug" risk without needing this
+    function to include provisional/superseded lessons.
     """
     out = []
     for line in (lessons_md or "").splitlines():
@@ -34,9 +40,9 @@ def _extract_lesson_lines(lessons_md):
             continue
         text = s[2:].split("<!--")[0].strip()
         if text.startswith("[PROVISIONAL]"):
-            text = text[len("[PROVISIONAL]"):].strip()
-        if text.startswith("~~") and text.endswith("~~") and len(text) >= 4:
-            text = text[2:-2].strip()
+            continue
+        if text.startswith("~~") and text.endswith("~~"):
+            continue
         if text:
             out.append(text)
     return out

From 16dc21c6ad040b8a82762d9bc8148265b32547c4 Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 03:45:01 +0530
Subject: [PATCH 06/10] fix(.agent): address fifth codex review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P1] _extract_lesson_lines now reads the status= field from each
  rendered bullet's HTML annotation. Only status="accepted" counts
  as terminal; legacy (migrated from pre-restructure LESSONS.md)
  and provisional lessons can now recur through the duplicate gate
  for re-review or supersession. Visual-marker check is kept as a
  fallback for unannotated bullets.

- [P1] render_lessons now dedupes lessons.jsonl by id before
  rendering (keeps the latest entry per id). Without this, a
  provisional→accepted state transition would render both rows as
  separate bullets with the same claim. The jsonl stays
  append-only for audit; the rendered markdown shows the current
  state.

- [P2] write_candidates now cleans up the graduated/ copy when it
  re-stages a provisional lesson. Previously the same slug could
  live in both staged and graduated at once, making
  list_candidates --status graduated show stale data.
---
 .agent/memory/promote.py        | 10 ++++++----
 .agent/memory/render_lessons.py | 25 +++++++++++++++++++++++--
 .agent/memory/validate.py       | 26 +++++++++++++++-----------
 3 files changed, 44 insertions(+), 17 deletions(-)

diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index 3b11c53..0162567 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -121,11 +121,13 @@ def write_candidates(patterns, candidates_dir):
         with open(staged_path, "w") as f:
             json.dump(candidate, f, indent=2)
 
-        # If the candidate was previously rejected, remove it from the
-        # rejected subdir so the same id isn't tracked in two states at once.
-        if prev_loc == "rejected":
+        # The slug must live in exactly one lifecycle location. Remove any
+        # prior copy in rejected/ or graduated/ (the latter only for
+        # provisional re-review — accepted never gets here because it's
+        # skipped above).
+        if prev_loc in ("rejected", "graduated"):
             try:
-                os.remove(os.path.join(candidates_dir, "rejected", f"{slug}.json"))
+                os.remove(os.path.join(candidates_dir, prev_loc, f"{slug}.json"))
             except OSError:
                 pass
         written += 1
diff --git a/.agent/memory/render_lessons.py b/.agent/memory/render_lessons.py
index cc2ac69..794228a 100644
--- a/.agent/memory/render_lessons.py
+++ b/.agent/memory/render_lessons.py
@@ -148,16 +148,37 @@ def migrate_legacy_bullets(semantic_dir):
     return migrated
 
 
+def _dedupe_by_id(lessons):
+    """Keep the latest entry per lesson id.
+
+    lessons.jsonl is append-only, so a provisional→accepted state transition
+    writes two rows with the same id. The render should show only the latest
+    state for each lesson; the jsonl is preserved for audit.
+    """
+    latest = {}
+    order = []
+    for L in lessons:
+        lid = L.get("id")
+        if not lid:
+            # No id? Treat as-is, keyed by its position so we keep it.
+            lid = f"_anon_{len(order)}"
+        if lid not in latest:
+            order.append(lid)
+        latest[lid] = L
+    return [latest[lid] for lid in order]
+
+
 def render_lessons(semantic_dir):
     """Re-render LESSONS.md. Preserves hand-curated content above the sentinel.
 
     Auto-migrates legacy auto-promoted bullets below the sentinel into
     lessons.jsonl before rendering, so upgrades from the old markdown-only
-    format don't silently erase past promotions.
+    format don't silently erase past promotions. Deduplicates entries by
+    lesson id so a provisional-then-accepted lesson renders once, not twice.
     """
     # First, absorb any un-registered bullets below the sentinel
     migrate_legacy_bullets(semantic_dir)
-    lessons = load_lessons(semantic_dir)
+    lessons = _dedupe_by_id(load_lessons(semantic_dir))
     auto_section = _build_auto_section(lessons)
 
     path = os.path.join(semantic_dir, LESSONS_MD)
diff --git a/.agent/memory/validate.py b/.agent/memory/validate.py
index d628e38..f0da7a2 100644
--- a/.agent/memory/validate.py
+++ b/.agent/memory/validate.py
@@ -11,6 +11,8 @@
 LENGTH_SATURATE = 100
 CLUSTER_SATURATE = 5
 
+_STATUS_RE = re.compile(r"status=(\w+)")
+
 
 def _normalize(text):
     """Lowercase, strip punctuation, collapse whitespace. For exact-dup detection."""
@@ -21,24 +23,26 @@ def _normalize(text):
 def _extract_lesson_lines(lessons_md):
     """Extract accepted lesson claims from rendered markdown.
 
-    Only TERMINAL lessons count for duplicate detection:
-      - `[PROVISIONAL]` lessons are probationary; if a pattern recurs, the
-        host agent should see it for evidence accumulation or full
-        graduation. Blocking them here makes provisional an accidental
-        dead end.
-      - Strikethrough (`~~...~~`) lessons are superseded; a new claim that
-        happens to match a superseded one is a legitimate revival, not a
-        duplicate.
-    Stable candidate ids (derived from claim text in cluster.extract_pattern)
-    handle the "same claim under different slug" risk without needing this
-    function to include provisional/superseded lessons.
+    Only TERMINAL lessons count for duplicate detection. Non-terminal status
+    values — `provisional` (probationary), `legacy` (imported from pre-restructure
+    LESSONS.md), and anything superseded — must be skipped so recurrences can
+    reach the host agent for re-review, evidence accumulation, or supersession.
+    Status is read from the HTML annotation written by render_lessons; visual
+    markers (`[PROVISIONAL]`, `~~...~~`) are the fallback for unannotated lines.
     """
     out = []
     for line in (lessons_md or "").splitlines():
         s = line.strip()
         if not s.startswith("- ") or len(s) <= 2:
             continue
+        # Primary signal: status in HTML annotation
+        if "<!--" in s:
+            ann = s.split("<!--", 1)[1]
+            m = _STATUS_RE.search(ann)
+            if m and m.group(1) != "accepted":
+                continue
         text = s[2:].split("<!--")[0].strip()
+        # Fallback: visual markers (for pre-existing bullets without annotations)
         if text.startswith("[PROVISIONAL]"):
             continue
         if text.startswith("~~") and text.endswith("~~"):

From 1e480f3ca8058ce7873f28d0f946d981e0838955 Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 03:55:01 +0530
Subject: [PATCH 07/10] fix(.agent): address sixth codex review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P1] Candidate re-stage gate now keys off actual change signals,
  not reviewer identity. mark_rejected and mark_graduated stamp the
  most recent decision with {evidence_snapshot, lessons_sha}.
  write_candidates compares the current cluster's evidence_ids +
  current LESSONS.md hash against the stamp and re-stages only if
  something material shifted. This fixes two failure modes:
  (a) human-rejected candidates no longer churn every dream cycle
  when the same evidence keeps producing the same cluster, and
  (b) heuristic-rejected candidates are no longer permanently
  suppressed — if the accepted lesson that triggered the duplicate
  rejection is later superseded or removed, the pattern comes back
  for review.

- [P2] context_budget._top_lessons now filters by status, so only
  accepted lessons reach the host agent's system prompt.
  Previously superseded (~~...~~), [PROVISIONAL], and legacy
  bullets could be injected as active guidance, letting the agent
  act on stale or probationary memory. Uses the same status=
  annotation parsing as validate._extract_lesson_lines (kept in
  sync by comment; duplication preferred over cross-layer import
  between harness/ and memory/).
---
 .agent/harness/context_budget.py | 36 ++++++++++++++++++++++++--------
 .agent/memory/promote.py         | 29 ++++++++++++++++---------
 .agent/memory/review_state.py    | 35 ++++++++++++++++++++++++++++++-
 3 files changed, 80 insertions(+), 20 deletions(-)

diff --git a/.agent/harness/context_budget.py b/.agent/harness/context_budget.py
index 67692c5..718edc4 100644
--- a/.agent/harness/context_budget.py
+++ b/.agent/harness/context_budget.py
@@ -5,7 +5,7 @@
 in general. Always-on slots (PREFERENCES, WORKSPACE, permissions) are loaded
 whole regardless of query — they're cheap and safety-critical.
 """
-import json, os, sys
+import json, os, re, sys
 from salience import salience_score
 from text import word_set, jaccard
 
@@ -15,6 +15,10 @@
 sys.path.insert(0, os.path.join(ROOT, "tools"))
 RELEVANCE_FLOOR = 0.3  # even zero-overlap episodes surface if very salient
 
+# Keep in sync with memory/validate._extract_lesson_lines — both filters
+# want TERMINAL-only lesson content.
+_STATUS_RE = re.compile(r"status=(\w+)")
+
 
 def _read(path, limit=None):
     full = os.path.join(ROOT, path)
@@ -85,20 +89,34 @@ def _lines_up_to_budget(lines, char_budget):
 
 
 def _top_lessons(query, lessons_md, char_budget=8000):
-    """Rank LESSONS.md bullets by query overlap; fall back to original order.
+    """Rank accepted lesson bullets by query overlap; fall back to original order.
 
-    Section headers (## ...) get dropped when ranking — the LLM only needs
-    the distilled claim lines. When the query has zero overlap with any
-    bullet, fall back to the original order so the agent still sees general
-    knowledge.
+    Only terminal (status=accepted) lessons reach the host agent as retrievable
+    guidance. Provisional, legacy, and superseded bullets exist in LESSONS.md
+    for audit but must not be injected into the system prompt — they'd let the
+    agent act on probationary or stale memory.
     """
     lines = []
     for line in (lessons_md or "").splitlines():
         s = line.strip()
-        if s.startswith("- ") and len(s) > 2:
-            lines.append(s[2:].split("<!--")[0].strip())
+        if not s.startswith("- ") or len(s) <= 2:
+            continue
+        # Primary status filter: HTML annotation
+        if "<!--" in s:
+            ann = s.split("<!--", 1)[1]
+            m = _STATUS_RE.search(ann)
+            if m and m.group(1) != "accepted":
+                continue
+        text = s[2:].split("<!--")[0].strip()
+        # Fallback: visual markers
+        if text.startswith("[PROVISIONAL]"):
+            continue
+        if text.startswith("~~") and text.endswith("~~"):
+            continue
+        if text:
+            lines.append(text)
     if not lines:
-        return lessons_md[:char_budget]
+        return lessons_md[:char_budget] if lessons_md else ""
 
     query_words = word_set(query)
     if not query_words:
diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index 0162567..f0b5b8c 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -10,6 +10,7 @@
 """
 import os, json, datetime, hashlib
 from cluster import content_cluster, extract_pattern
+from review_state import _lessons_sha
 
 
 def cluster_and_extract(entries, threshold=0.3):
@@ -69,6 +70,8 @@ def write_candidates(patterns, candidates_dir):
         return 0
     os.makedirs(candidates_dir, exist_ok=True)
     written = 0
+    current_lessons_sha = _lessons_sha(candidates_dir)
+
     for key, p in patterns.items():
         claim = (p.get("claim") or "").strip()
         if not claim:
@@ -78,20 +81,26 @@ def write_candidates(patterns, candidates_dir):
         slug = _slug(p)
         prev, prev_loc = _find_prior(slug, candidates_dir)
 
-        # Fully-accepted lesson — don't resurrect. Provisional acceptance is
-        # probationary, so recurring provisional patterns SHOULD reappear
-        # for re-review + evidence accumulation.
+        # Fully-accepted lesson — terminal, never resurrect.
         if prev_loc == "graduated" and prev.get("status") != "provisional":
             continue
 
-        # Heuristic-rejected candidates (length / exact-duplicate of an
-        # existing lesson) are terminal unless a human reopens them. Without
-        # this guard, each dream cycle would re-stage the same slug and
-        # heuristic_prefilter would immediately reject it again, bumping
-        # rejection_count forever for no new signal.
-        if prev_loc == "rejected":
+        # For rejected + provisional-graduated, re-stage ONLY when something
+        # material has changed since the last decision. Comparing reviewer
+        # identity ("heuristic" vs "human") was a blunt proxy; what actually
+        # matters is whether evidence or the semantic landscape shifted.
+        if prev_loc in ("rejected", "graduated"):
             last = (prev.get("decisions") or [])[-1] if prev.get("decisions") else {}
-            if last.get("action") == "rejected" and last.get("reviewer") == "heuristic_prefilter":
+            prev_evidence = set(last.get("evidence_snapshot", []))
+            new_evidence = set(p.get("evidence_ids", []))
+            evidence_changed = prev_evidence != new_evidence
+            # Lessons-hash only matters for rejections (heuristic rejections
+            # depend on LESSONS.md contents). Provisional re-review gates on
+            # evidence alone.
+            stamp = last.get("lessons_sha", "")
+            lessons_changed = (prev_loc == "rejected" and stamp != "" and
+                               stamp != current_lessons_sha)
+            if not evidence_changed and not lessons_changed:
                 continue
 
         now = datetime.datetime.now().isoformat()
diff --git a/.agent/memory/review_state.py b/.agent/memory/review_state.py
index 2780411..9df7634 100644
--- a/.agent/memory/review_state.py
+++ b/.agent/memory/review_state.py
@@ -9,7 +9,7 @@
 history so a candidate that keeps reappearing is visibly churning rather
 than looking novel each time.
 """
-import os, json, datetime
+import os, json, datetime, hashlib
 
 
 def _now():
@@ -27,6 +27,37 @@ def _touch(candidate, action, reviewer, notes="", **fields):
     })
 
 
+def _lessons_sha(candidates_dir):
+    """Short hash of current LESSONS.md, used to stamp decisions.
+
+    Re-staging logic uses this to tell 'semantic state changed since this
+    decision' apart from 'nothing has changed, skip to avoid churn'.
+    """
+    lessons_path = os.path.join(
+        os.path.dirname(candidates_dir), "semantic", "LESSONS.md")
+    if not os.path.exists(lessons_path):
+        return ""
+    try:
+        with open(lessons_path, "rb") as f:
+            return hashlib.md5(f.read()).hexdigest()[:12]
+    except OSError:
+        return ""
+
+
+def _stamp_evidence_and_lessons(cand, candidates_dir):
+    """Attach evidence + lessons snapshots to the most recent decision.
+
+    Called on every terminal-ish transition (rejected, graduated). Lets
+    write_candidates decide whether a later re-detection represents genuinely
+    new information or the same state we already judged.
+    """
+    if not cand.get("decisions"):
+        return
+    last = cand["decisions"][-1]
+    last["evidence_snapshot"] = list(cand.get("evidence_ids", []))
+    last["lessons_sha"] = _lessons_sha(candidates_dir)
+
+
 def load_candidate(path):
     with open(path) as f:
         return json.load(f)
@@ -83,6 +114,7 @@ def mark_graduated(candidate_id, reviewer, rationale, candidates_dir,
     cand["rationale"] = rationale
     _touch(cand, "graduated", reviewer, notes=rationale,
            provisional=provisional)
+    _stamp_evidence_and_lessons(cand, candidates_dir)
 
     graduated_dir = os.path.join(candidates_dir, "graduated")
     os.makedirs(graduated_dir, exist_ok=True)
@@ -106,6 +138,7 @@ def mark_rejected(candidate_id, reviewer, reason, candidates_dir):
     cand["status"] = "rejected"
     cand["rejection_count"] = cand.get("rejection_count", 0) + 1
     _touch(cand, "rejected", reviewer, notes=reason)
+    _stamp_evidence_and_lessons(cand, candidates_dir)
 
     rejected_dir = os.path.join(candidates_dir, "rejected")
     os.makedirs(rejected_dir, exist_ok=True)

From 839ef4e41d76b1cd57d9a1b230bdf6742cb95629 Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 04:11:56 +0530
Subject: [PATCH 08/10] fix(.agent): address seventh codex review round

- [P1] Pattern id now derives from normalized claim + conditions
  (sorted shared tokens). Claim-only id collided for generic
  canonical text ("the test failed" in db context vs api context
  would overwrite). Conditions usually stay stable across cluster
  membership changes, so lifecycle continuity is preserved in the
  common case while genuinely-different clusters get distinct ids.

- [P1] graduate.py is now atomic in the right direction: append to
  lessons.jsonl + render LESSONS.md FIRST, then move the candidate
  file to graduated/. Previously the move happened before the
  semantic writes; an interruption in the middle left the
  candidate terminal-filed but the lesson unlogged, which was a
  silent data-loss path. Append-only jsonl + dedupe-by-id at
  render time mean a retry after crash produces one rendered
  bullet, not two.

- [P2] Re-stage gate for heuristic-rejected candidates now
  compares the SPECIFIC lesson(s) that blocked them, not the
  whole-file LESSONS.md hash. heuristic_prefilter stamps
  duplicate_claims on the rejection decision; write_candidates
  checks whether any of those claims still exist as terminal
  lessons. Unrelated graduations no longer trigger re-staging +
  auto-rejection + rejection_count inflation. validate's
  _extract_lesson_lines is renamed extract_lesson_lines so
  promote can reuse the status-aware terminal filter.
---
 .agent/memory/auto_dream.py   |  7 ++++++-
 .agent/memory/cluster.py      | 16 +++++++++-----
 .agent/memory/promote.py      | 39 ++++++++++++++++++++++++++---------
 .agent/memory/review_state.py | 10 +++++++--
 .agent/memory/validate.py     |  4 ++--
 .agent/tools/graduate.py      | 22 +++++++++++++-------
 6 files changed, 71 insertions(+), 27 deletions(-)

diff --git a/.agent/memory/auto_dream.py b/.agent/memory/auto_dream.py
index e1eb2eb..1e6ffb0 100644
--- a/.agent/memory/auto_dream.py
+++ b/.agent/memory/auto_dream.py
@@ -75,7 +75,12 @@ def _heuristic_prefilter(candidates_dir, semantic_dir):
         check = heuristic_check(cand, existing)
         if not check["passed"]:
             reason = ", ".join(check["reasons"])
-            mark_rejected(cand["id"], "heuristic_prefilter", reason, candidates_dir)
+            # Record the specific lesson(s) that triggered the duplicate
+            # rejection so write_candidates can check whether THIS blocker
+            # is still there, not just whether LESSONS.md as a whole changed.
+            mark_rejected(cand["id"], "heuristic_prefilter", reason,
+                          candidates_dir,
+                          duplicate_claims=check.get("duplicates", []))
             rejected += 1
     return rejected
 
diff --git a/.agent/memory/cluster.py b/.agent/memory/cluster.py
index e1992c5..5ade021 100644
--- a/.agent/memory/cluster.py
+++ b/.agent/memory/cluster.py
@@ -85,11 +85,17 @@ def extract_pattern(cluster):
 
     top_terms = sorted(common, key=lambda t: (-len(t), t))[:3]
     name_base = "_".join(top_terms) if top_terms else "untitled"
-    # Stable id: derived from the normalized claim text, NOT cluster membership.
-    # If an extra episode joins or leaves the cluster the canonical claim is
-    # usually unchanged, so the id is unchanged, so the candidate's lifecycle
-    # history (rejection_count, graduated/provisional state) carries forward.
-    pattern_id = hashlib.md5(_normalize_claim(claim).encode()).hexdigest()[:12]
+    # Id derived from normalized claim + conditions (shared tokens). Claim
+    # alone would collide for generic canonical text (e.g., "the test
+    # failed") occurring in unrelated contexts. Conditions usually stay
+    # stable as cluster members shift (intersection of the cluster's common
+    # vocabulary), so lifecycle history carries across membership changes
+    # in the common case while genuinely-different clusters with the same
+    # canonical get distinct ids.
+    conditions_key = "|".join(sorted(common))
+    pattern_id = hashlib.md5(
+        (_normalize_claim(claim) + "||" + conditions_key).encode()
+    ).hexdigest()[:12]
     name = f"pattern_{name_base}_{pattern_id[:6]}"
 
     # Recurrence-aware salience: give the scoring function cluster context
diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index f0b5b8c..d2b45a7 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -11,6 +11,7 @@
 import os, json, datetime, hashlib
 from cluster import content_cluster, extract_pattern
 from review_state import _lessons_sha
+from validate import extract_lesson_lines
 
 
 def cluster_and_extract(entries, threshold=0.3):
@@ -70,13 +71,23 @@ def write_candidates(patterns, candidates_dir):
         return 0
     os.makedirs(candidates_dir, exist_ok=True)
     written = 0
-    current_lessons_sha = _lessons_sha(candidates_dir)
+    # Read LESSONS.md once — used to check whether specific duplicates that
+    # blocked a prior heuristic rejection are still present.
+    lessons_path = os.path.join(
+        os.path.dirname(candidates_dir), "semantic", "LESSONS.md")
+    lessons_text = ""
+    if os.path.exists(lessons_path):
+        try:
+            lessons_text = open(lessons_path).read()
+        except OSError:
+            pass
+    current_terminal_lessons = set(extract_lesson_lines(lessons_text))
 
     for key, p in patterns.items():
         claim = (p.get("claim") or "").strip()
         if not claim:
             continue
-        # Prefer the claim-derived id from extract_pattern — stable slug
+        # Prefer the claim+conditions id from extract_pattern — stable slug
         # means lifecycle state carries across cluster membership changes.
         slug = _slug(p)
         prev, prev_loc = _find_prior(slug, candidates_dir)
@@ -88,19 +99,27 @@ def write_candidates(patterns, candidates_dir):
         # For rejected + provisional-graduated, re-stage ONLY when something
         # material has changed since the last decision. Comparing reviewer
         # identity ("heuristic" vs "human") was a blunt proxy; what actually
-        # matters is whether evidence or the semantic landscape shifted.
+        # matters is whether evidence or the specific blocker shifted.
         if prev_loc in ("rejected", "graduated"):
             last = (prev.get("decisions") or [])[-1] if prev.get("decisions") else {}
             prev_evidence = set(last.get("evidence_snapshot", []))
             new_evidence = set(p.get("evidence_ids", []))
             evidence_changed = prev_evidence != new_evidence
-            # Lessons-hash only matters for rejections (heuristic rejections
-            # depend on LESSONS.md contents). Provisional re-review gates on
-            # evidence alone.
-            stamp = last.get("lessons_sha", "")
-            lessons_changed = (prev_loc == "rejected" and stamp != "" and
-                               stamp != current_lessons_sha)
-            if not evidence_changed and not lessons_changed:
+
+            # Did the specific lesson(s) that triggered this rejection go
+            # away? Uses stamped duplicate_claims rather than a whole-file
+            # LESSONS.md hash — unrelated graduations no longer cause
+            # heuristic-rejected candidates to churn.
+            stamped_dups = last.get("duplicate_claims") or []
+            if stamped_dups:
+                blocker_still_present = any(
+                    d in current_terminal_lessons for d in stamped_dups)
+            else:
+                # No specific stamp (older rejection or human reject).
+                # Provisional and human-rejected cases gate on evidence alone.
+                blocker_still_present = True
+
+            if not evidence_changed and blocker_still_present:
                 continue
 
         now = datetime.datetime.now().isoformat()
diff --git a/.agent/memory/review_state.py b/.agent/memory/review_state.py
index 9df7634..7eee543 100644
--- a/.agent/memory/review_state.py
+++ b/.agent/memory/review_state.py
@@ -125,11 +125,17 @@ def mark_graduated(candidate_id, reviewer, rationale, candidates_dir,
     return cand
 
 
-def mark_rejected(candidate_id, reviewer, reason, candidates_dir):
+def mark_rejected(candidate_id, reviewer, reason, candidates_dir, **extra_stamp):
     """Move a staged candidate to candidates/rejected/ with a reject decision.
 
     rejection_count tracks how many times this id has been rejected — if it
     keeps coming back, the reviewer sees churn instead of a 'fresh' item.
+
+    extra_stamp kwargs are merged into the decision entry. heuristic_prefilter
+    uses this to record which specific lessons triggered the duplicate rejection
+    (duplicate_claims=[...]); write_candidates later checks whether those
+    specific lessons are still present before re-staging, so unrelated LESSONS
+    edits don't cause the candidate to churn.
     """
     src = os.path.join(candidates_dir, f"{candidate_id}.json")
     if not os.path.exists(src):
@@ -137,7 +143,7 @@ def mark_rejected(candidate_id, reviewer, reason, candidates_dir):
     cand = load_candidate(src)
     cand["status"] = "rejected"
     cand["rejection_count"] = cand.get("rejection_count", 0) + 1
-    _touch(cand, "rejected", reviewer, notes=reason)
+    _touch(cand, "rejected", reviewer, notes=reason, **extra_stamp)
     _stamp_evidence_and_lessons(cand, candidates_dir)
 
     rejected_dir = os.path.join(candidates_dir, "rejected")
diff --git a/.agent/memory/validate.py b/.agent/memory/validate.py
index f0da7a2..338df24 100644
--- a/.agent/memory/validate.py
+++ b/.agent/memory/validate.py
@@ -20,7 +20,7 @@ def _normalize(text):
     return re.sub(r"\s+", " ", t).strip()
 
 
-def _extract_lesson_lines(lessons_md):
+def extract_lesson_lines(lessons_md):
     """Extract accepted lesson claims from rendered markdown.
 
     Only TERMINAL lessons count for duplicate detection. Non-terminal status
@@ -57,7 +57,7 @@ def check_exact_duplicate(claim, existing_lessons_md):
     nc = _normalize(claim)
     if not nc:
         return []
-    return [l for l in _extract_lesson_lines(existing_lessons_md)
+    return [l for l in extract_lesson_lines(existing_lessons_md)
             if _normalize(l) == nc]
 
 
diff --git a/.agent/tools/graduate.py b/.agent/tools/graduate.py
index 7b05fea..de0bb11 100644
--- a/.agent/tools/graduate.py
+++ b/.agent/tools/graduate.py
@@ -6,7 +6,7 @@
 caught. The rationale is REQUIRED — rubber-stamped promotions are the
 whole failure mode this layer is designed to prevent.
 """
-import os, sys, json, argparse, hashlib
+import os, sys, json, argparse, hashlib, datetime
 
 BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
 sys.path.insert(0, os.path.join(BASE, "memory"))
@@ -51,18 +51,20 @@ def main():
               file=sys.stderr)
         sys.exit(2)
 
-    graduated = mark_graduated(
-        args.candidate_id, args.reviewer, args.rationale, CANDIDATES,
-        provisional=args.provisional,
-    )
-
+    # Atomicity: write to semantic memory BEFORE moving the candidate.
+    # If we crash mid-graduation, the staged candidate remains and the
+    # reviewer can retry. Append-only lessons.jsonl is deduped by id at
+    # render time, so a retry that re-appends produces one lesson bullet,
+    # not two. Crashing AFTER the move would leave the candidate lost and
+    # the lesson unlogged — the failure mode this reorder prevents.
+    accepted_at = datetime.datetime.now().isoformat()
     lesson = {
         "id": _lesson_id(cand),
         "claim": cand.get("claim"),
         "conditions": cand.get("conditions", []),
         "evidence_ids": cand.get("evidence_ids", []),
         "status": "provisional" if args.provisional else "accepted",
-        "accepted_at": graduated.get("accepted_at"),
+        "accepted_at": accepted_at,
         "reviewer": args.reviewer,
         "rationale": args.rationale,
         "cluster_size": cand.get("cluster_size", 1),
@@ -76,6 +78,12 @@ def main():
     append_lesson(lesson, SEMANTIC)
     md_path = render_lessons(SEMANTIC)
 
+    # Semantic writes survived — now move the candidate file.
+    mark_graduated(
+        args.candidate_id, args.reviewer, args.rationale, CANDIDATES,
+        provisional=args.provisional,
+    )
+
     print(f"graduated {args.candidate_id} → lesson {lesson['id']}")
     print(f"re-rendered: {md_path}")
 

From f9ddc6969fb81ca9bdf15f41d45c88e5fdd2cabb Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 04:20:58 +0530
Subject: [PATCH 09/10] fix(.agent): address eighth codex review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P1] graduate._lesson_id now keys off candidate.id (claim+
  conditions, stable) instead of md5(claim). Two distinct
  candidates with the same canonical claim (e.g., "the test
  failed" in db vs api context) used to produce the same
  lesson_id; dedupe_by_id would silently drop the earlier
  accepted lesson from LESSONS.md.

- [P2] context_budget._top_lessons now returns "" when no
  accepted lessons exist, instead of falling back to raw
  markdown. The fallback leaked exactly the provisional/
  legacy/superseded content the status filter is designed to
  block — agent could act on stale memory right after
  migration or during pure-provisional states.

- [P2] content_cluster is now actually single-linkage. The old
  loop appended to the FIRST matching cluster but never merged
  other clusters the new entry also connected to, so input
  order [A, C, B] where A~B and B~C but A⊄C produced
  [[A,B], [C]] instead of one 3-item cluster. Recurrence counts
  and promotion thresholds were order-dependent as a result.
  Fix: find ALL clusters the new entry connects to, absorb
  them into one.
---
 .agent/harness/context_budget.py |  4 +++-
 .agent/memory/cluster.py         | 36 +++++++++++++++++++-------------
 .agent/tools/graduate.py         | 12 +++++++++++
 3 files changed, 37 insertions(+), 15 deletions(-)

diff --git a/.agent/harness/context_budget.py b/.agent/harness/context_budget.py
index 718edc4..1dc7045 100644
--- a/.agent/harness/context_budget.py
+++ b/.agent/harness/context_budget.py
@@ -116,7 +116,9 @@ def _top_lessons(query, lessons_md, char_budget=8000):
         if text:
             lines.append(text)
     if not lines:
-        return lessons_md[:char_budget] if lessons_md else ""
+        # No accepted lessons → return empty. Returning raw markdown would
+        # leak the non-terminal content the filter is designed to block.
+        return ""
 
     query_words = word_set(query)
     if not query_words:
diff --git a/.agent/memory/cluster.py b/.agent/memory/cluster.py
index 5ade021..4e3964f 100644
--- a/.agent/memory/cluster.py
+++ b/.agent/memory/cluster.py
@@ -37,13 +37,15 @@ def _entry_features(entry):
 def content_cluster(entries, threshold=0.3, min_size=2):
     """Single-linkage agglomerative clustering on Jaccard similarity.
 
-    An entry joins the first cluster where any member's similarity meets
-    threshold. Entries with empty feature sets are dropped (they can't
-    cluster meaningfully — jaccard on two empty sets returns 1.0 in the
-    shared helper, so we filter here rather than fight the math).
-
-    Returns only clusters with >= min_size members so singletons don't
-    create candidate churn.
+    An entry joins every existing cluster it's similar to, and all such
+    clusters merge into one — proper single-linkage. Without the merge
+    step, ordering matters: entries [A, C, B] where A~B~C but A⊄C would
+    produce two clusters [A,B] + [C] instead of one, so recurrence
+    counts and promotion thresholds become input-order dependent.
+
+    Entries with empty feature sets are dropped (jaccard of two empty
+    sets would otherwise be 1.0). Clusters smaller than min_size are
+    filtered so singletons don't create candidate churn.
     """
     featured = [(e, _entry_features(e)) for e in entries]
     featured = [(e, fs) for e, fs in featured if fs]
@@ -51,14 +53,20 @@ def content_cluster(entries, threshold=0.3, min_size=2):
     clusters = []  # each: list of (entry, feature_set)
     for item in featured:
         e_i, fs_i = item
-        joined = False
-        for c in clusters:
-            if any(jaccard(fs_i, fs_j) >= threshold for _, fs_j in c):
-                c.append(item)
-                joined = True
-                break
-        if not joined:
+        matching_indices = [
+            i for i, c in enumerate(clusters)
+            if any(jaccard(fs_i, fs_j) >= threshold for _, fs_j in c)
+        ]
+        if not matching_indices:
             clusters.append([item])
+            continue
+        # Merge the new item + every cluster it connects to into one.
+        target = clusters[matching_indices[0]]
+        target.append(item)
+        # Absorb the rest, tail-first so indexing stays valid.
+        for idx in reversed(matching_indices[1:]):
+            target.extend(clusters[idx])
+            del clusters[idx]
 
     return [[e for e, _ in c] for c in clusters if len(c) >= min_size]
 
diff --git a/.agent/tools/graduate.py b/.agent/tools/graduate.py
index de0bb11..c0b63d6 100644
--- a/.agent/tools/graduate.py
+++ b/.agent/tools/graduate.py
@@ -20,6 +20,18 @@
 
 
 def _lesson_id(candidate):
+    """1:1 with the candidate's own id (claim + conditions, stable).
+
+    Using md5(claim) alone collides when two distinct patterns happen to
+    share canonical text — different clusters about different situations
+    with the same "the test failed" reflection, etc. Keying off the
+    candidate id keeps them distinct and matches how write_candidates
+    identifies the pattern lifecycle.
+    """
+    cid = candidate.get("id") or ""
+    if cid:
+        return f"lesson_{cid}"
+    # Fallback for older candidate dicts without `id`
     claim = (candidate.get("claim") or "").strip().lower()
     return "lesson_" + hashlib.md5(claim.encode()).hexdigest()[:12]
 

From d347186b8875b1c39d5ca6f2927a195bfef35973 Mon Sep 17 00:00:00 2001
From: codejunkie99 <email@email.com>
Date: Fri, 17 Apr 2026 04:28:09 +0530
Subject: [PATCH 10/10] fix(.agent): address ninth codex review round
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- [P2] Provisional supersessions no longer blank the active lesson.
  _build_auto_section now applies the superseded_by map only when
  the superseder is status="accepted". A provisional --supersedes
  was silently making the old accepted lesson render as
  ~~strikethrough~~ while the replacement was still probationary,
  so retrieval skipped both — the topic went dark.

- [P2] graduate.py --supersedes now excludes the superseded
  lesson from the exact-duplicate check. Replacing a lesson with
  structurally better content (updated conditions, fresh
  evidence, revised status) but the same claim wording is the
  whole point of supersession; the heuristic was blocking it with
  exact_duplicate_of_*.

- [P2] Re-stage gate now only counts NEW evidence (new_evidence
  minus prev_evidence), not set inequality. Decay archives old
  low-salience episodes every dream cycle; without this fix,
  routine evidence shrinkage would flip evidence_changed=True
  even when nothing new arrived, recreating churn for patterns
  whose only change was decay.
---
 .agent/memory/promote.py        | 6 +++++-
 .agent/memory/render_lessons.py | 7 +++++++
 .agent/tools/graduate.py        | 8 ++++++++
 3 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/.agent/memory/promote.py b/.agent/memory/promote.py
index d2b45a7..66efca8 100644
--- a/.agent/memory/promote.py
+++ b/.agent/memory/promote.py
@@ -104,7 +104,11 @@ def write_candidates(patterns, candidates_dir):
             last = (prev.get("decisions") or [])[-1] if prev.get("decisions") else {}
             prev_evidence = set(last.get("evidence_snapshot", []))
             new_evidence = set(p.get("evidence_ids", []))
-            evidence_changed = prev_evidence != new_evidence
+            # Only NEW supporting episodes count as a change worth re-review.
+            # Equality comparison would trigger on routine decay (old evidence
+            # archived out of the cluster), even though nothing new arrived
+            # and the original blocker is unchanged.
+            evidence_changed = bool(new_evidence - prev_evidence)
 
             # Did the specific lesson(s) that triggered this rejection go
             # away? Uses stamped duplicate_claims rather than a whole-file
diff --git a/.agent/memory/render_lessons.py b/.agent/memory/render_lessons.py
index 794228a..97cafb0 100644
--- a/.agent/memory/render_lessons.py
+++ b/.agent/memory/render_lessons.py
@@ -62,8 +62,15 @@ def _bullet_for(lesson, superseded_by):
 
 
 def _build_auto_section(lessons):
+    # Only accepted supersessions flip the old lesson to strikethrough.
+    # A provisional --supersedes would otherwise blank the active lesson
+    # before its replacement has been accepted, leaving no active guidance
+    # on that topic at all (retrieval skips both provisional and
+    # strikethrough).
     superseded_by = {}
     for L in lessons:
+        if L.get("status") != "accepted":
+            continue
         sup = L.get("supersedes")
         if sup:
             superseded_by[sup] = L.get("id")
diff --git a/.agent/tools/graduate.py b/.agent/tools/graduate.py
index c0b63d6..628d02f 100644
--- a/.agent/tools/graduate.py
+++ b/.agent/tools/graduate.py
@@ -57,6 +57,14 @@ def main():
 
     lessons_md = os.path.join(SEMANTIC, "LESSONS.md")
     existing = open(lessons_md).read() if os.path.exists(lessons_md) else ""
+    # When superseding, exclude the target lesson from the duplicate check —
+    # replacing a lesson with structurally-better content but same wording
+    # is exactly what supersession is for.
+    if args.supersedes:
+        existing = "\n".join(
+            line for line in existing.splitlines()
+            if f"id={args.supersedes}" not in line
+        )
     check = heuristic_check(cand, existing)
     if not check["passed"]:
         print(f"ERROR: candidate fails heuristic check: {check['reasons']}",