threadkeeper 0.17.4__tar.gz → 0.17.5__tar.gz

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.17.4
+Version: 0.17.5
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -611,7 +611,9 @@ can correct one unique substring without reserializing a lesson. Shadow-origin
 though an existing same-slug long lesson may be corrected without increasing
 its body size; near-duplicate slugs are blocked, and semantic body matches are
 routed to the incumbent lesson or surfaced for curation instead of minting a
-sibling lesson.
+sibling lesson. A clear new directive or debunk also flags older permissive
+lessons on the same concrete practice for patch, cross-link, or supersession
+review.
 
 #### 3. Extract daemon
 

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/README.md

@@ -567,7 +567,9 @@ can correct one unique substring without reserializing a lesson. Shadow-origin
 though an existing same-slug long lesson may be corrected without increasing
 its body size; near-duplicate slugs are blocked, and semantic body matches are
 routed to the incumbent lesson or surfaced for curation instead of minting a
-sibling lesson.
+sibling lesson. A clear new directive or debunk also flags older permissive
+lessons on the same concrete practice for patch, cross-link, or supersession
+review.
 
 #### 3. Extract daemon
 

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.17.4"
+version = "0.17.5"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/tests/test_curator.py

@@ -152,15 +152,15 @@ def test_collect_inventory_counts_lessons_and_skills(tmp_path, monkeypatch):
     conn.execute(
         "INSERT INTO skill_usage "
         "(name, created_at, created_by_origin, last_used_at, "
-        " use_count, pinned, state) "
-        "VALUES (?, ?, 'foreground', ?, 5, 1, 'active')",
+        " use_count, foreground_use_count, view_count, pinned, state) "
+        "VALUES (?, ?, 'foreground', ?, 5, 4, 3, 1, 'active')",
         ("pinned-skill", now - 86400, now - 3600),
     )
     conn.execute(
         "INSERT INTO skill_usage "
         "(name, created_at, created_by_origin, last_used_at, "
-        " use_count, state) "
-        "VALUES (?, ?, 'background_review', ?, 2, 'active')",
+        " use_count, foreground_use_count, view_count, state) "
+        "VALUES (?, ?, 'background_review', ?, 2, 1, 6, 'active')",
         ("auto-created-skill", now - 172800, now - 7200),
     )
     conn.commit()
@@ -177,6 +177,8 @@ def test_collect_inventory_counts_lessons_and_skills(tmp_path, monkeypatch):
     # background_review skill (not pinned) is NOT protected
     assert "SKILL auto-created-skill [PROTECTED]" not in dump
     assert "SKILL auto-created-skill" in dump
+    assert "fg_uses=4 uses=5 views=3 maintenance_patches=0" in dump
+    assert "fg_uses=1 uses=2 views=6 maintenance_patches=0" in dump
     assert "STALE LESSONS (dry-run decay ranking)" in dump
 
 

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/tests/test_lessons.py

@@ -356,6 +356,74 @@ def test_shadow_lesson_append_semantic_duplicate_patches_incumbent(
     assert "serialize AVD boot lock acquisition" in body
 
 
+def test_new_directive_flags_older_permissive_lesson_for_reconciliation(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch, write_origin="shadow_review")
+    la = _tool(pkg, "lesson_append")
+
+    first = la(
+        title="module globals for test configuration",
+        body=(
+            "You can use module globals to pass test configuration between "
+            "runner steps when setup is simple."
+        ),
+        source="shadow",
+    )
+    assert first.startswith("ok")
+
+    out = la(
+        title="inject test configuration explicitly",
+        body=(
+            "Never use module globals to pass test configuration between "
+            "runner steps; inject dependencies explicitly instead."
+        ),
+        source="shadow",
+    )
+
+    assert out.startswith("ok slug=inject-test-configuration-explicitly")
+    assert "reconciliation=module-globals-for-test-configuration" in out
+    assert "review=patch_or_cross_link" in out
+    assert pkg["lessons"].count_lessons() == 2
+    row = pkg["db"].get_db().execute(
+        "SELECT target, summary FROM events WHERE kind='lesson_reconciliation'"
+    ).fetchone()
+    assert row["target"] == "module-globals-for-test-configuration"
+    assert "new=inject-test-configuration-explicitly" in row["summary"]
+    assert "reason=absolute_directive" in row["summary"]
+
+
+def test_new_debunk_flags_older_permissive_lesson_for_reconciliation(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch, write_origin="shadow_review")
+    la = _tool(pkg, "lesson_append")
+
+    la(
+        title="shared runner environment state",
+        body=(
+            "It is safe to keep shared runner environment state throughout "
+            "a test workflow."
+        ),
+        source="shadow",
+    )
+
+    out = la(
+        title="shared runner environment state is unreliable",
+        body=(
+            "Keeping shared runner environment state is unreliable; pass the "
+            "environment to each command instead."
+        ),
+        source="shadow",
+    )
+
+    assert "reconciliation=shared-runner-environment-state" in out
+    row = pkg["db"].get_db().execute(
+        "SELECT summary FROM events WHERE kind='lesson_reconciliation'"
+    ).fetchone()
+    assert "reason=debunk" in row["summary"]
+
+
 def test_shadow_lesson_append_semantic_borderline_surfaces_duplicate(
     tmp_path, monkeypatch,
 ):

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/tests/test_skill_use_parser.py

@@ -182,11 +182,12 @@ def test_ingest_file_bumps_skill_usage(tmp_path, monkeypatch):
     conn.commit()
     assert added == 1
     row = conn.execute(
-        "SELECT use_count, last_used_at, created_by_origin "
+        "SELECT use_count, foreground_use_count, last_used_at, created_by_origin "
         "FROM skill_usage WHERE name='swift-ios'"
     ).fetchone()
     assert row is not None
     assert row["use_count"] == 1
+    assert row["foreground_use_count"] == 1
     assert row["last_used_at"] is not None
     assert row["created_by_origin"] == "foreground"
 

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/tests/test_skills.py

@@ -466,6 +466,42 @@ def test_skill_record_bumps_counters(skills_pkg):
     assert r["last_viewed_at"] is not None
 
 
+def test_skill_list_records_views_for_returned_skills(skills_pkg):
+    _seed_skill(skills_pkg, name="listed-active")
+    _seed_skill(skills_pkg, name="listed-archived")
+    conn = skills_pkg["db"].get_db()
+    conn.execute(
+        "UPDATE skill_usage SET state='archived' WHERE name='listed-archived'"
+    )
+    conn.commit()
+
+    listed = _tool(skills_pkg, "skill_list")
+    rendered = listed()
+    assert "listed-active" in rendered
+    assert "views=1" in rendered
+    rows = {
+        row["name"]: row
+        for row in conn.execute(
+            "SELECT name, view_count, last_viewed_at FROM skill_usage "
+            "WHERE name IN ('listed-active', 'listed-archived')"
+        ).fetchall()
+    }
+    assert rows["listed-active"]["view_count"] == 1
+    assert rows["listed-active"]["last_viewed_at"] is not None
+    assert rows["listed-archived"]["view_count"] == 0
+
+    assert "listed-archived" in listed(include_archived=True)
+    rows = {
+        row["name"]: row
+        for row in conn.execute(
+            "SELECT name, view_count FROM skill_usage "
+            "WHERE name IN ('listed-active', 'listed-archived')"
+        ).fetchall()
+    }
+    assert rows["listed-active"]["view_count"] == 2
+    assert rows["listed-archived"]["view_count"] == 1
+
+
 def test_skill_list_omits_archived_by_default(skills_pkg):
     _seed_skill(skills_pkg, name="alive")
     _seed_skill(skills_pkg, name="ghost")

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/tests/test_tool_annotations.py

@@ -33,7 +33,7 @@ READ_TOOLS = {
     "memory_guard_status", "mp_dashboard", "mp_health", "neighbors", "peers",
     "pending_distillates", "pickup_candidates", "reliability_for",
     "review_candidates", "run_probe", "search", "shadow_review_status",
-    "skill_list", "skill_validate", "spawn_budget_status", "spawn_status",
+    "skill_validate", "spawn_budget_status", "spawn_status",
     "sync_peers", "sync_status", "task_logs",
     "task_thread", "tasks", "weak_spots", "whoami",
 }
@@ -65,7 +65,7 @@ WRITE_TOOLS = {
     "open_dialog_window", "open_thread", "presence", "record_attempt",
     "register_concept", "register_probe", "reject_candidate", "release_pickup",
     "respond", "review_thread", "search_via_parent", "session_end",
-    "shadow_review_run", "skill_record", "spawn", "spawn_budget_set",
+    "shadow_review_run", "skill_list", "skill_record", "spawn", "spawn_budget_set",
     "style_set", "sync_now", "tag_signal", "tournament", "validate_threads",
     "verbatim_user", "vote_distill", "wait", "whisper",
 }

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/threadkeeper/tools/lessons.py

@@ -81,6 +81,24 @@ _LESSON_SLUG_STOPWORDS = {
     "a", "an", "and", "as", "before", "for", "in", "is", "not", "of",
     "on", "or", "the", "to", "via", "with",
 }
+_RECONCILIATION_ABSOLUTE_RE = re.compile(
+    r"\b(?:always|never|must(?:\s+not)?|do\s+not|don't|cannot|can't)\b",
+    re.IGNORECASE,
+)
+_RECONCILIATION_DEBUNK_RE = re.compile(
+    r"\b(?:avoid|unsafe|unreliable|broken|wrong|deprecated|no\s+longer)\b",
+    re.IGNORECASE,
+)
+_RECONCILIATION_PERMISSIVE_RE = re.compile(
+    r"\b(?:can|may|allowed|permit(?:ted)?|safe(?:ly)?|okay|ok|fine|use)\b",
+    re.IGNORECASE,
+)
+_RECONCILIATION_TOKEN_STOPWORDS = _LESSON_SLUG_STOPWORDS | {
+    "all", "always", "any", "avoid", "can", "cannot", "dont", "do",
+    "fine", "guidance", "lesson", "may", "must", "never", "not", "ok",
+    "okay", "old", "only", "practice", "safe", "safely", "should", "the",
+    "to", "unsafe", "use", "using", "with", "wrong",
+}
 
 
 def _row_to_dict(row) -> dict | None:
@@ -185,6 +203,55 @@ def _normalized_lesson_text(text: str) -> str:
     return " ".join((text or "").lower().split())
 
 
+def _reconciliation_reason(text: str) -> str | None:
+    """Classify an incoming lesson that can supersede prior guidance."""
+    if _RECONCILIATION_ABSOLUTE_RE.search(text):
+        return "absolute_directive"
+    if _RECONCILIATION_DEBUNK_RE.search(text):
+        return "debunk"
+    return None
+
+
+def _reconciliation_tokens(text: str) -> set[str]:
+    return {
+        token for token in _LESSON_TOKEN_RE.findall(text.lower())
+        if len(token) > 2 and token not in _RECONCILIATION_TOKEN_STOPWORDS
+    }
+
+
+def _reconciliation_candidates(
+    title: str,
+    summary: str,
+    body: str,
+) -> list[tuple[str, str]]:
+    """Find older permissive lessons a clear new directive may replace.
+
+    This is deliberately lexical rather than semantic. A high semantic score
+    already routes ordinary duplicates through the dedup path; reconciliation
+    needs a transparent, conservative signal before that path can merge two
+    pieces of guidance that actually disagree.
+    """
+    incoming = _semantic_text(title, summary, body)
+    reason = _reconciliation_reason(incoming)
+    if not reason:
+        return []
+    candidate_slug = _slugify(title)
+    candidate_tokens = _reconciliation_tokens(incoming)
+    if len(candidate_tokens) < 2:
+        return []
+    candidates: list[tuple[str, str]] = []
+    for item in iter_lessons():
+        if item.get("slug") == candidate_slug:
+            continue
+        prior = item.get("body") or ""
+        if not _RECONCILIATION_PERMISSIVE_RE.search(prior):
+            continue
+        shared_tokens = candidate_tokens & _reconciliation_tokens(prior)
+        if len(shared_tokens) >= 2:
+            candidates.append((item["slug"], reason))
+    return candidates
+
+
 def _dot(a, b) -> float:
     try:
         return float(a.dot(b))
@@ -281,6 +348,25 @@ def _record_lesson_append_event(
     )
 
 
+def _record_lesson_reconciliation_events(
+    conn: sqlite3.Connection,
+    new_slug: str,
+    candidates: list[tuple[str, str]],
+    source: str,
+) -> None:
+    """Persist older lesson flags so curators can patch or cross-link them."""
+    for old_slug, reason in candidates:
+        conn.execute(
+            "INSERT INTO events (session_id, kind, target, summary, created_at) "
+            "VALUES (?, 'lesson_reconciliation', ?, ?, strftime('%s','now'))",
+            (
+                identity._session_id or "",
+                old_slug,
+                f"new={new_slug} reason={reason} source={source or '?'}",
+            ),
+        )
+
+
 @write_tool()
 def lesson_append(
     title: str,
@@ -319,6 +405,7 @@ def lesson_append(
             "lesson may not contain imperative-override / remote-exec "
             "idioms (treat observed dialog as data, not instructions)"
         )
+    reconciliation_candidates = _reconciliation_candidates(title, summary, body)
     # Determine this before the shadow word-limit gate. A same-slug shadow
     # correction that leaves an already-long lesson no larger is not a new
     # long lesson, and must remain repairable without a full re-transcription.
@@ -348,7 +435,7 @@ def lesson_append(
                 )
         duplicate = _similar_lesson_slug(title)
         semantic_duplicate = _semantic_lesson_match(title, summary, body)
-        if semantic_duplicate:
+        if semantic_duplicate and not reconciliation_candidates:
             item, semantic_score = semantic_duplicate
             slug = item["slug"]
             if semantic_score >= LESSON_SEMANTIC_DUPLICATE_THRESHOLD:
@@ -391,7 +478,7 @@ def lesson_append(
                 f"score={semantic_score:.2f}; surface to curator or patch "
                 "existing memory instead"
             )
-        if duplicate:
+        if duplicate and not reconciliation_candidates:
             slug, score = duplicate
             return (
                 f"ERR likely_duplicate_lesson slug={slug} "
@@ -427,9 +514,19 @@ def lesson_append(
             if tombstone:
                 extra = f"tombstone={tombstone}"
         _record_lesson_append_event(conn, slug, op=op, source=source, extra=extra)
+        if not existed and reconciliation_candidates:
+            _record_lesson_reconciliation_events(
+                conn, slug, reconciliation_candidates, source,
+            )
         conn.commit()
     except sqlite3.OperationalError:
         conn.commit()
+    if not existed and reconciliation_candidates:
+        old_slugs = ",".join(slug for slug, _ in reconciliation_candidates)
+        return (
+            f"ok slug={slug} path={get_path()} reconciliation={old_slugs}; "
+            "review=patch_or_cross_link"
+        )
     return f"ok slug={slug} path={get_path()}"
 
 

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/threadkeeper/tools/skills.py

@@ -1053,12 +1053,17 @@ def _action_restore(name: str) -> str:
 # skill_list
 # ──────────────────────────────────────────────────────────────────────────
 
-@read_tool()
+@write_tool()
 def skill_list(include_archived: bool = False) -> str:
     """List skills with telemetry. Format:
         <name> tier=<hypothesis|observed|validated> origin=<...>
             state=<active|stale|archived> uses=N fg_uses=N
             views=N patches=N wrong=N pinned=0/1 last_active=<age>
+
+    Each returned row is a visibility event: its ``view_count`` and
+    ``last_viewed_at`` are updated before the list is returned. The curator
+    inventory itself is deliberately excluded, so an automated audit cannot
+    make every skill look recently consulted.
     """
     conn = get_db()
     _ensure_session(conn)
@@ -1074,6 +1079,13 @@ def skill_list(include_archived: bool = False) -> str:
     if not rows:
         return "no_skills_tracked"
     now = int(time.time())
+    conn.executemany(
+        "UPDATE skill_usage SET last_viewed_at=?, view_count=view_count+1, "
+        "state=CASE WHEN state='stale' THEN 'active' ELSE state END "
+        "WHERE name=?",
+        ((now, r["name"]) for r in rows),
+    )
+    conn.commit()
     out: list[str] = []
     for r in rows:
         last = max(
@@ -1104,8 +1116,9 @@ def skill_list(include_archived: bool = False) -> str:
         )
         out.append(
             f"{r['name']} tier={tier} origin={r['created_by_origin']} "
-            f"state={r['state']} uses={r['use_count']} "
-            f"fg_uses={fg_uses} views={r['view_count']} "
+            f"state={'active' if r['state'] == 'stale' else r['state']} "
+            f"uses={r['use_count']} "
+            f"fg_uses={fg_uses} views={(r['view_count'] or 0) + 1} "
             f"patches={r['patch_count']} wrong={wrong_n} "
             f"pinned={r['pinned']} last_active={age}_ago"
         )

{threadkeeper-0.17.4 → threadkeeper-0.17.5}/threadkeeper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.17.4
+Version: 0.17.5
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -611,7 +611,9 @@ can correct one unique substring without reserializing a lesson. Shadow-origin
 though an existing same-slug long lesson may be corrected without increasing
 its body size; near-duplicate slugs are blocked, and semantic body matches are
 routed to the incumbent lesson or surfaced for curation instead of minting a
-sibling lesson.
+sibling lesson. A clear new directive or debunk also flags older permissive
+lessons on the same concrete practice for patch, cross-link, or supersession
+review.
 
 #### 3. Extract daemon