threadkeeper 0.23.0__tar.gz → 0.24.0__tar.gz

{threadkeeper-0.23.0/threadkeeper.egg-info → threadkeeper-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.23.0
+Version: 0.24.0
 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
@@ -1041,8 +1041,13 @@ trees, validators, and mirror state. It persists the full pass audit manifest
 for parent coordination and provenance, then writes one smaller, hash-checked
 audit slice for every frozen batch. A worker reads only its slice: assigned
 skill records and their relevant consumer, link, mirror, source, duplicate, and
-candidate findings. A lesson-only batch receives an explicit no-skills slice
-instead of the full skill inventory. The scheduler stores the expected reports,
+candidate findings, plus integrity evidence for its assigned lessons and any
+promotion source lessons. A lesson-only batch receives its lesson evidence
+with an explicit no-skills marker. Curator audit schema 3 records exact and
+normalized lesson body hashes, content-addressed revisions, safe provenance,
+usage times, sorted link targets and unresolved links, and duplicate candidates.
+Lesson text and lesson source paths stay out of the manifest; free-form
+provenance is hashed. The scheduler stores the expected reports,
 slice hashes, and rendered text before launching any child. A dispatch is not
 completion: every batch must exit successfully and have a final, matching
 provenance record before the inventory is endorsed.
@@ -1056,7 +1061,16 @@ successfully empty source remains valid, while a failed one records
 creating a recovery snapshot, or launching a child.
 
 A pass keeps reviewing the batches it froze even when the live inventory
-changes, and resuming it never re-reads the inventory. Failed and timed-out
+changes. Before evaluation and report writing, it checks the assigned lessons'
+live revisions. The prompt flags changed or removed lessons for DEFER, and the
+server adds a `CURATOR_AUDIT` header to each report with the frozen manifest
+schema version, SHA-256, reviewed revisions, and observed revision changes.
+Report writing and completion verify the saved manifest and batch slice;
+changed audit files cannot authorize a final report or endorsement. The frozen
+manifest stays unchanged, so a later pass can review the new lesson revision.
+Schema 1 and 2 skill-only manifests retain their original report contract;
+unsupported versions fail with `unsupported_curator_audit_version`.
+Resuming does not rebuild the full inventory. Failed and timed-out
 batches are retried without redispatching completed work, up to three launched
 attempts per batch; a spawn memory or spend-budget refusal leaves the batch
 waiting without using an attempt (a spend-cap refusal also alerts). A pass

{threadkeeper-0.23.0 → threadkeeper-0.24.0}/README.md

@@ -994,8 +994,13 @@ trees, validators, and mirror state. It persists the full pass audit manifest
 for parent coordination and provenance, then writes one smaller, hash-checked
 audit slice for every frozen batch. A worker reads only its slice: assigned
 skill records and their relevant consumer, link, mirror, source, duplicate, and
-candidate findings. A lesson-only batch receives an explicit no-skills slice
-instead of the full skill inventory. The scheduler stores the expected reports,
+candidate findings, plus integrity evidence for its assigned lessons and any
+promotion source lessons. A lesson-only batch receives its lesson evidence
+with an explicit no-skills marker. Curator audit schema 3 records exact and
+normalized lesson body hashes, content-addressed revisions, safe provenance,
+usage times, sorted link targets and unresolved links, and duplicate candidates.
+Lesson text and lesson source paths stay out of the manifest; free-form
+provenance is hashed. The scheduler stores the expected reports,
 slice hashes, and rendered text before launching any child. A dispatch is not
 completion: every batch must exit successfully and have a final, matching
 provenance record before the inventory is endorsed.
@@ -1009,7 +1014,16 @@ successfully empty source remains valid, while a failed one records
 creating a recovery snapshot, or launching a child.
 
 A pass keeps reviewing the batches it froze even when the live inventory
-changes, and resuming it never re-reads the inventory. Failed and timed-out
+changes. Before evaluation and report writing, it checks the assigned lessons'
+live revisions. The prompt flags changed or removed lessons for DEFER, and the
+server adds a `CURATOR_AUDIT` header to each report with the frozen manifest
+schema version, SHA-256, reviewed revisions, and observed revision changes.
+Report writing and completion verify the saved manifest and batch slice;
+changed audit files cannot authorize a final report or endorsement. The frozen
+manifest stays unchanged, so a later pass can review the new lesson revision.
+Schema 1 and 2 skill-only manifests retain their original report contract;
+unsupported versions fail with `unsupported_curator_audit_version`.
+Resuming does not rebuild the full inventory. Failed and timed-out
 batches are retried without redispatching completed work, up to three launched
 attempts per batch; a spawn memory or spend-budget refusal leaves the batch
 waiting without using an attempt (a spend-cap refusal also alerts). A pass

{threadkeeper-0.23.0 → threadkeeper-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.23.0"
+version = "0.24.0"
 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.23.0 → threadkeeper-0.24.0}/tests/test_curator.py

@@ -136,7 +136,9 @@ def _complete_manifest_batch(pkg, *, pass_id: str | None = None) -> str:
     ).fetchone()
     report = pkg["reports_dir"] / batch["report_name"]
     report.parent.mkdir(parents=True, exist_ok=True)
-    report.write_text("# report\n\nCURATOR_PASS_COMPLETE\n", encoding="utf-8")
+    header, error = pkg["curator"].curator_report_audit_header(conn, pass_id, batch["report_name"])
+    assert error is None
+    report.write_text(header + "# report\n\nCURATOR_PASS_COMPLETE\n", encoding="utf-8")
     digest = pkg["curator"].curator_report_sha256(report.read_text())
     now = int(time.time())
     conn.execute(
@@ -967,7 +969,7 @@ def test_run_curator_pass_spawns_when_threshold_met(tmp_path, monkeypatch):
         if not path.name.startswith("AUDIT-SLICE-")
     ]
     assert len(manifests) == 1
-    assert json.loads(manifests[0].read_text())["schema_version"] == 2
+    assert json.loads(manifests[0].read_text())["schema_version"] == 3
     slices = list(pkg["reports_dir"].glob("AUDIT-SLICE-*.json"))
     assert len(slices) == 1
     assert f"AUDIT_MANIFEST_SLICE_PATH = {slices[0]}" in kw["prompt"]
@@ -1072,6 +1074,14 @@ def test_curator_reuses_verified_audit_slice_and_rejects_tampering(
     assert first.prompt == second.prompt
     assert slice_path.read_text() == original
 
+    altered_batch = dict(batch_row)
+    altered_batch["batch_text"] = batch_row["batch_text"].replace(
+        "AUDIT_MANIFEST_SCHEMA_VERSION = 3", "AUDIT_MANIFEST_SCHEMA_VERSION = 2",
+    )
+    assert pkg["curator"]._evaluate_spec(
+        conn, pass_row, altered_batch, "evaluate", 1,
+    ) == "audit_batch_manifest_binding_mismatch"
+
     slice_path.write_text("{}\n", encoding="utf-8")
     assert pkg["curator"]._evaluate_spec(
         conn, pass_row, batch_row, "evaluate", 1,
@@ -1119,6 +1129,91 @@ def test_worker_audit_input_scales_with_assigned_skill_records():
     assert worker_input_size < canonical_size * len(slices) // 2
 
 
+def test_lesson_changes_during_a_pass_are_in_prompt_and_final_report(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, min_lessons="2")
+    _two_shadow_lessons(pkg)
+    _recording_spawn(monkeypatch)
+    pkg["curator"].run_curator_pass(force=True)
+    conn = pkg["db"].get_db()
+    pass_row = conn.execute("SELECT * FROM curator_passes").fetchone()
+    batch = conn.execute("SELECT * FROM curator_batches").fetchone()
+    frozen_raw = Path(pass_row["audit_manifest_path"]).read_text()
+    manifest = json.loads(frozen_raw)
+    assert len(manifest["lesson_audit"]["lessons"]) == 2
+    assert f"AUDIT_MANIFEST_SHA256 = {pass_row['audit_manifest_sha256']}" in batch["batch_text"]
+    original = pkg["lessons_path"].read_text()
+    pkg["lessons_path"].write_text(original.replace("body one", "updated body one"))
+    spec = pkg["curator"]._evaluate_spec(conn, pass_row, batch, "evaluate", 1)
+    assert '"lesson_revision_changes":[{"current_revision":' in spec.prompt
+    assert '"slug":"lesson-one"' in spec.prompt
+    assert "mark those lessons DEFER" in spec.prompt
+
+    from threadkeeper.tools import curator as tool_mod
+    from threadkeeper._mcp import mcp
+    from threadkeeper.curator_audit import REPORT_AUDIT_PREFIX
+    monkeypatch.setattr(tool_mod, "WRITE_ORIGIN", "curator")
+    monkeypatch.setattr(tool_mod, "SPAWNED_CHILD", True)
+    monkeypatch.setenv("THREADKEEPER_CURATOR_PASS_ID", pass_row["pass_id"])
+    _bind_curator_writer(pkg, pass_row["pass_id"])
+    write = mcp._tool_manager._tools["curator_report_write"].fn
+    assert write(content="Changed lesson: DEFER\nCURATOR_PASS_COMPLETE").startswith("ok path=")
+    report = (pkg["reports_dir"] / batch["report_name"]).read_text()
+    receipt = json.loads(report.splitlines()[0][len(REPORT_AUDIT_PREFIX):-4])
+    assert receipt["schema_version"] == 3
+    assert receipt["sha256"] == pass_row["audit_manifest_sha256"]
+    assert [change["slug"] for change in receipt["lesson_revision_changes"]] == ["lesson-one"]
+    assert pkg["curator"]._provenanced_report(
+        conn, pass_row["pass_id"], batch["report_name"], "CURATOR_PASS_COMPLETE",
+    ) is not None
+    assert Path(pass_row["audit_manifest_path"]).read_text() == frozen_raw
+
+
+@pytest.mark.parametrize("state", ["running", "complete"])
+def test_changed_audit_file_blocks_report_write_and_completion(tmp_path, monkeypatch, state):
+    pkg = _bootstrap(tmp_path, monkeypatch, min_lessons="2")
+    _two_shadow_lessons(pkg)
+    _recording_spawn(monkeypatch)
+    pkg["curator"].run_curator_pass(force=True)
+    conn = pkg["db"].get_db()
+    pass_id = _complete_manifest_batch(pkg)
+    pass_row = conn.execute("SELECT * FROM curator_passes").fetchone()
+    batch = conn.execute("SELECT * FROM curator_batches").fetchone()
+    conn.execute("UPDATE curator_batches SET state=?", (state,))
+    conn.commit()
+    Path(pass_row["audit_manifest_path"]).write_text("{}\n")
+    header, error = pkg["curator"].curator_report_audit_header(conn, pass_id, batch["report_name"])
+    assert header == ""
+    assert error == "canonical_manifest_mismatch"
+    from threadkeeper import evolve_applier
+    report = pkg["reports_dir"] / batch["report_name"]
+    assert not evolve_applier._curator_report_provenanced(conn, report, report.read_text())
+    assert not pkg["curator"]._refresh_pass_completion(conn, pass_id, int(time.time()))
+    assert conn.execute("SELECT endorsed_at FROM curator_passes").fetchone()[0] is None
+
+
+def test_report_provenance_requires_the_frozen_lesson_revision_receipt(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch, min_lessons="2")
+    _two_shadow_lessons(pkg)
+    _recording_spawn(monkeypatch)
+    pkg["curator"].run_curator_pass(force=True)
+    conn = pkg["db"].get_db()
+    pass_id = _complete_manifest_batch(pkg)
+    batch = conn.execute("SELECT * FROM curator_batches").fetchone()
+    report = pkg["reports_dir"] / batch["report_name"]
+    content = report.read_text().replace('"schema_version":3', '"schema_version":2', 1)
+    report.write_text(content)
+    digest = pkg["curator"].curator_report_sha256(content)
+    conn.execute(
+        "INSERT INTO events (session_id, kind, target, summary, created_at) VALUES (?, ?, ?, ?, ?)",
+        (_FAKE_CID, pkg["curator"].CURATOR_REPORT_PROVENANCE_KIND, str(report.resolve()),
+         f"pass_id={pass_id} sha256={digest}", int(time.time())),
+    )
+    conn.commit()
+    assert pkg["curator"]._provenanced_report(
+        conn, pass_id, batch["report_name"], "CURATOR_PASS_COMPLETE",
+    ) is None
+
+
 def test_web_research_receives_only_public_brief_and_narrow_tools(
     tmp_path, monkeypatch,
 ):
@@ -2892,7 +2987,12 @@ def _finish_child(pkg, *, task_id, report_name, content, return_code=0):
     conn = pkg["db"].get_db()
     report = pkg["reports_dir"] / report_name
     report.parent.mkdir(parents=True, exist_ok=True)
-    report.write_text(content, encoding="utf-8")
+    pass_id = conn.execute(
+        "SELECT pass_id FROM curator_passes ORDER BY created_at DESC LIMIT 1"
+    ).fetchone()["pass_id"]
+    header, error = pkg["curator"].curator_report_audit_header(conn, pass_id, report_name)
+    assert error is None
+    report.write_text(header + content, encoding="utf-8")
     digest = pkg["curator"].curator_report_sha256(report.read_text())
     now = int(time.time())
     conn.execute(
@@ -2901,9 +3001,6 @@ def _finish_child(pkg, *, task_id, report_name, content, return_code=0):
         "VALUES (?, 0, '/tmp', 'curator', ?, ?, ?)",
         (task_id, now - 1, now, return_code),
     )
-    pass_id = conn.execute(
-        "SELECT pass_id FROM curator_passes ORDER BY created_at DESC LIMIT 1"
-    ).fetchone()["pass_id"]
     conn.execute(
         "INSERT INTO events (session_id, kind, target, summary, created_at) "
         "VALUES (?, ?, ?, ?, ?)",

threadkeeper-0.24.0/tests/test_curator_audit.py

@@ -0,0 +1,164 @@
+"""Lesson audit evidence is reproducible, private, and version bound."""
+import copy
+import hashlib
+import json
+
+import pytest
+
+
+def _item(slug="alpha", body="Review release evidence before publishing.", **kwargs):
+    return {
+        "slug": slug, "body": body, "ts": 123, "source": "shadow",
+        "origin": "shadow_review", "usage": {}, **kwargs,
+    }
+
+
+def _audit(items):
+    from threadkeeper.curator_audit import build_curator_audit
+    return build_curator_audit({"schema_version": 2, "skills": [{"name": "skill-target"}]}, items)
+
+
+def _serialized(manifest):
+    from threadkeeper.skill_audit import serialized_skill_audit
+    return serialized_skill_audit(manifest)
+
+
+def _slice(manifest, slugs=("alpha",)):
+    from threadkeeper.curator_audit import build_batch_audit_slice
+    return build_batch_audit_slice(
+        manifest, pass_id="pass", batch_index=1, batch_total=1,
+        inventory_fingerprint="f" * 64, canonical_manifest_sha256="a" * 64,
+        assigned_skill_names=[], assigned_lesson_slugs=slugs,
+    )
+
+
+def test_lesson_hashes_and_manifest_serialization_are_deterministic():
+    from threadkeeper.lesson_freshness import lesson_revision
+    items = [_item("beta"), _item("alpha", usage={"last_used_at": 50, "last_viewed_at": 60})]
+    first = _audit(items)
+    second = _audit(list(reversed(items)))
+    assert _serialized(first) == _serialized(second)
+    assert first["schema_version"] == 3
+    records = first["lesson_audit"]["lessons"]
+    assert [record["slug"] for record in records] == ["alpha", "beta"]
+    assert records[0]["body_sha256"] == hashlib.sha256(items[1]["body"].encode()).hexdigest()
+    assert records[0]["revision"] == lesson_revision(items[1])
+    assert records[0]["timestamp"] == 123
+    assert records[0]["usage"]["last_used_at"] == 50
+    assert records[0]["usage"]["last_viewed_at"] == 60
+
+
+def test_body_edit_changes_revision_and_manifest_digest_but_usage_does_not_change_revision():
+    before = _audit([_item()])
+    after = _audit([_item(body="Changed release rule.")])
+    digest = lambda manifest: hashlib.sha256(_serialized(manifest).encode()).hexdigest()
+    assert digest(before) != digest(after)
+    for key in ("body_sha256", "normalized_body_sha256", "revision"):
+        assert before["lesson_audit"]["lessons"][0][key] != after["lesson_audit"]["lessons"][0][key]
+    usage = _audit([_item(usage={"view_count": 10})])
+    assert before["lesson_audit"]["lessons"][0]["revision"] == usage["lesson_audit"]["lessons"][0]["revision"]
+
+
+def test_links_include_adjacency_skill_targets_aliases_and_unresolved_targets():
+    audit = _audit([
+        _item("alpha", "[[beta]] [[beta|alias]] [[missing]] [[skill-target]] [[alpha]]"),
+        _item("beta", "[[zebra]] [[missing]]"),
+    ])["lesson_audit"]
+    alpha, beta = audit["lessons"]
+    assert alpha["outgoing_links"] == ["alpha", "beta", "missing", "skill-target"]
+    assert alpha["adjacent_lessons"] == ["beta"]
+    assert beta["adjacent_lessons"] == ["alpha"]
+    assert alpha["unresolved_links"] == ["missing"]
+    assert beta["unresolved_links"] == ["missing", "zebra"]
+
+
+def test_exact_normalized_and_near_duplicate_groups_are_sorted_and_body_free():
+    audit = _audit([
+        _item("beta", "Check release evidence before publishing"),
+        _item("alpha", "Check release evidence before publishing"),
+        _item("gamma", "CHECK release evidence, before publishing!"),
+        _item("delta", "Check release evidence before publishing safely"),
+    ])["lesson_audit"]
+    assert audit["exact_duplicate_groups"][0]["lessons"] == ["alpha", "beta"]
+    assert audit["normalized_duplicate_groups"][0]["lessons"] == ["alpha", "beta", "gamma"]
+    assert any(pair["left"] == "alpha" and pair["right"] == "delta" for pair in audit["near_duplicate_candidates"])
+    assert all(set(pair) == {"left", "right", "token_jaccard", "status"} for pair in audit["near_duplicate_candidates"])
+
+
+def test_protected_lesson_body_and_private_provenance_paths_never_enter_audit():
+    item = _item(
+        body="PRIVATE_BODY /Users/private/project.md C:\\private\\project [[skill-target]]",
+        source="/Users/private/source.md", origin="/private/origin",
+        usage={"pinned": 1, "source": "C:\\private\\source", "tier": "validated"},
+    )
+    manifest = _audit([item])
+    encoded = _serialized(manifest)
+    for private in ("PRIVATE_BODY", "/Users/private", "/private/origin", "C:\\private"):
+        assert private not in encoded
+    record = manifest["lesson_audit"]["lessons"][0]
+    assert record["protected"] is True
+    assert record["protection_reason"] == "pinned"
+    assert record["provenance"]["source_kind"] == "redacted"
+    assert record["provenance"]["origin"] == "unknown"
+    assert record["provenance"]["source_sha256"] == hashlib.sha256(item["source"].encode()).hexdigest()
+
+
+def test_lesson_slices_include_only_assigned_records_and_related_evidence():
+    manifest = _audit([_item("alpha"), _item("beta"), _item("unrelated", "Another rule entirely")])
+    sliced = _slice(manifest)
+    assert sliced["schema_version"] == 2
+    assert sliced["no_skills"] is True
+    assert sliced["assigned_lesson_slugs"] == ["alpha"]
+    assert [record["slug"] for record in sliced["lesson_audit"]["lessons"]] == ["alpha"]
+    assert sliced["lesson_audit"]["exact_duplicate_groups"][0]["lessons"] == ["alpha", "beta"]
+    assert "unrelated" not in json.dumps(sliced)
+    with pytest.raises(ValueError, match="lesson_audit_scope_missing"):
+        _slice(manifest, ["missing"])
+
+
+def test_report_receipt_records_changed_and_removed_lessons_and_rejects_other_revisions():
+    from threadkeeper.curator_audit import audit_receipt, report_audit_header, report_matches_audit
+    manifest = _slice(_audit([_item("alpha"), _item("beta")]), ["alpha", "beta"])
+    receipt = audit_receipt(manifest, [_item("alpha", "A new rule")])
+    assert [change["slug"] for change in receipt["lesson_revision_changes"]] == ["alpha", "beta"]
+    assert receipt["lesson_revision_changes"][1]["current_revision"] is None
+    report = report_audit_header(receipt) + "CURATOR_PASS_COMPLETE\n"
+    assert report_matches_audit(report, manifest)
+    assert not report_matches_audit("CURATOR_PASS_COMPLETE", manifest)
+    for key, value in (("sha256", "b" * 64), ("schema_version", 2), ("reviewed_revisions", {})):
+        changed = {**receipt, key: value}
+        assert not report_matches_audit(report_audit_header(changed), manifest)
+
+
+@pytest.mark.parametrize("version", [1, 2])
+def test_older_manifests_keep_their_original_slice_contract(version):
+    from threadkeeper.skill_audit import build_batch_skill_audit_slice
+    manifest = {"schema_version": version, "skills": []}
+    sliced = _slice(manifest, [])
+    assert sliced == build_batch_skill_audit_slice(
+        manifest, pass_id="pass", batch_index=1, batch_total=1,
+        inventory_fingerprint="f" * 64, canonical_manifest_sha256="a" * 64,
+        assigned_skill_names=[],
+    )
+
+
+@pytest.mark.parametrize("version", [None, True, "3", 0, 4])
+def test_unknown_manifest_versions_fail_clearly(version):
+    from threadkeeper.curator_audit import validate_manifest_version
+    with pytest.raises(ValueError, match="unsupported_curator_audit_version"):
+        validate_manifest_version({"schema_version": version})
+
+
+def test_promotion_sources_are_part_of_frozen_lesson_scope():
+    from threadkeeper.curator_audit import batch_lesson_slugs
+    assert batch_lesson_slugs(
+        "- LESSON beta [PROTECTED]\n    lessons: gamma, alpha\n- LESSON beta\n"
+    ) == ["alpha", "beta", "gamma"]
+
+
+def test_audit_builder_does_not_change_original_skill_manifest():
+    from threadkeeper.curator_audit import build_curator_audit
+    skills = {"schema_version": 2, "skills": []}
+    original = copy.deepcopy(skills)
+    build_curator_audit(skills, [_item()])
+    assert skills == original