"""Tests for okfwiki/klink.py, the link pass: code strips, asks, accepts and places links; the model proposes them. Wave 2, order 10 (K2 point 17): the guard. `homeless` takes the pages and sources the auditor's JSON findings name (no-main-page-link, main-page-missing), so the auditor is the only judge; the guard's task asks the model once for a home per page (or none) and a main page per source, from the pack's filtered catalogue of main pages and from the pages that cite the source; its answer is checked by code. The linker agent carries the guard's contract too. Every fixture is synthetic text about a kitchen garden (CLAUDE.md rule 3). Run: python3 -m unittest discover -s tests -p 'test_klink.py' """ from __future__ import annotations import io import json import shutil import sys import tempfile import unittest from unittest import mock from contextlib import redirect_stderr, redirect_stdout from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT)) from okfwiki import audit, klink # noqa: E402 from okfwiki.common import RunError # noqa: E402 def page(title: str, sources: list[tuple[str, str, int, str]], body: str) -> str: fm = ["---", "type: Concept", f"title: {title}", f"description: {title} in the garden.", "sources:"] for sid, resource, line, quote in sources: fm += [f" - id: {sid}", f" resource: {resource}", " title: Garden notes", f" x-locator: {{ line: {line} }}", f" x-quote: '{quote}'"] fm += ["generated: { by: claude-code/claude-opus-5-5, at: 2026-10-05T09:00:00Z }", "---", ""] return "\n".join(fm) + body GARDEN = "/kilde/garden.md" SOIL = "/kilde/soil.md" PAGES = { "tomato.md": page("Tomato", [("f1", GARDEN, 2, "Tomatoes need full sun"), ("f2", GARDEN, 3, "Basil grows well")], ( "# Tomato\n\n" "Tomatoes need full sun for most of the day.[^f1] A bed beside [basil](basil.md) suits them.[^f2] Stake them early.\n\n" "`[compost](compost.md)` is a note on the bed.[^f1]\n\n" "```\n[mulch](mulch.md)\n```\n\n" "## History of [soil](soil.md)\n\n" "- Plant after the last frost.[^f1]\n\n" "[^f1]: garden.md, line 2\n[^f2]: garden.md, line 3, see [basil](basil.md)\n")), "basil.md": page("Basil", [("f1", GARDEN, 3, "Basil grows well")], ( "# Basil\n\nBasil grows well next to tomatoes.[^f1]\n\n[^f1]: garden.md, line 3\n")), "compost.md": page("Compost", [("f1", GARDEN, 4, "Compost feeds the soil"), ("f2", SOIL, 2, "Rich soil")], ( "# Compost\n\n" "Compost feeds the soil over the winter.[^f1] Turn the `pile` weekly.[^f1] Turn the `heap` weekly.[^f1]\n" "Rich soil holds compost well.[^f2]\n\n" "[^f1]: garden.md, line 4\n[^f2]: soil.md, line 2\n")), "mulch.md": page("Mulch", [("f1", GARDEN, 5, "Mulch keeps the soil moist")], ( "# Mulch\n\nMulch keeps the soil moist in summer.[^f1] Water early.[^f1] Water early.[^f1]\n\n" "[^f1]: garden.md, line 5\n")), "soil.md": page("Soil", [("f1", SOIL, 2, "Rich soil")], ( "# Soil\n\nRich soil holds water and air.[^f1]\n\n[^f1]: soil.md, line 2\n")), "index.md": "# Garden\n\n" + "".join(f"* [{n.title()}]({n}.md)\n" for n in ("tomato", "basil", "compost", "mulch", "soil")), "log.md": "# Log\n\n## 2026-10-05\n* **Build**: added [Tomato](tomato.md).\n", } ACCEPTED = {"schema": "okf-wiki/p1-accepted/1", "fragments": [ {"pack": 1, "concept_id": "tomato", "text": "Tomatoes need full sun for most of the day."}, {"pack": 1, "concept_id": "tomato", "text": "A bed beside basil suits them"}, {"pack": 1, "concept_id": "basil", "text": "Basil grows well next to tomatoes."}, {"pack": 2, "concept_id": "compost", "text": "Compost feeds the soil over the winter."}, {"pack": 2, "concept_id": "mulch", "text": "Mulch keeps the soil moist in summer."}, ]} def run_main(argv: list[str]) -> tuple[int, str, str]: out, err = io.StringIO(), io.StringIO() with redirect_stdout(out), redirect_stderr(err): code = klink.main(argv) return code, out.getvalue(), err.getvalue() class Fixture(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.root = Path(self._tmp.name) self.bundle = self.root / "K" for name, text in PAGES.items(): (self.bundle / name).parent.mkdir(parents=True, exist_ok=True) (self.bundle / name).write_text(text, encoding="utf-8") self.accepted = self.root / "accepted.json" self.accepted.write_text(json.dumps(ACCEPTED), encoding="utf-8") self.stripped = self.root / "stripped" self.links = self.root / "links.json" def tearDown(self) -> None: self._tmp.cleanup() def strip(self) -> Path: self.assertEqual(0, run_main(["strip", str(self.bundle), "--out", str(self.stripped)])[0]) return self.stripped def sentences(self, bundle: Path, name: str) -> list[klink.Sentence]: return klink.page_sentences((bundle / name).read_text(encoding="utf-8")) def key(self, bundle: Path, name: str, starts: str, nth: int = 0) -> str: return [s.key for s in self.sentences(bundle, name) if s.text.startswith(starts)][nth] def propose(self, links: list[dict[str, str]], none: list[str] | None = None, name: str = "p.json") -> Path: p = self.root / name p.write_text(json.dumps({"links": links, "none": none or []}), encoding="utf-8") return p def accept(self, proposals: Path, bundle: Path) -> tuple[int, dict[str, Any]]: code = run_main(["accept", str(proposals), "--bundle", str(bundle), "--links", str(self.links)])[0] return code, json.loads(self.links.read_text(encoding="utf-8")) class StripTest(Fixture): def test_strip_removes_body_links_and_keeps_text(self) -> None: code, out, _ = run_main(["strip", str(self.bundle), "--out", str(self.stripped)]) self.assertEqual(0, code) self.assertIn("5 links", out) tomato = (self.stripped / "tomato.md").read_text(encoding="utf-8") self.assertIn("A bed beside basil suits them.[^f2]", tomato) self.assertEqual(PAGES["index.md"], (self.stripped / "index.md").read_text(encoding="utf-8")) self.assertEqual(PAGES["tomato.md"].split("\n---\n")[0], tomato.split("\n---\n")[0]) # frontmatter untouched def test_links_in_code_spans_blocks_headings_and_footnotes_are_stripped_too(self) -> None: # Plankontroll 05.10, addition 1: P1's K has two links in code spans; without this, Step 9 can never pass. before = audit.link_rule_report(audit.load_bundle(self.bundle, self.root)) self.assertEqual(4, before["misplaced"]) self.strip() tomato = (self.stripped / "tomato.md").read_text(encoding="utf-8") self.assertIn("`compost` is a note", tomato) self.assertIn("```\nmulch\n```", tomato) self.assertIn("## History of soil", tomato) report = audit.link_rule_report(audit.load_bundle(self.stripped, self.root)) self.assertEqual((0, 0, 0), (report["pass"], report["misplaced"], report["broken"])) def test_strip_refuses_an_existing_output(self) -> None: self.strip() self.assertEqual(2, run_main(["strip", str(self.bundle), "--out", str(self.stripped)])[0]) class SentenceKeyTest(Fixture): def test_the_key_is_the_same_before_and_after_place(self) -> None: stripped = self.strip() before = [s.key for s in self.sentences(stripped, "tomato.md")] self.assertEqual(before, [s.key for s in self.sentences(self.bundle, "tomato.md")]) # links reduced first def test_sentences_differing_only_inside_backticks_get_different_keys(self) -> None: keys = {s.text: s.key for s in self.sentences(self.bundle, "compost.md")} self.assertNotEqual(keys["Turn the `pile` weekly.[^f1]"], keys["Turn the `heap` weekly.[^f1]"]) def test_two_identical_sentences_on_one_page_get_distinct_keys(self) -> None: water = [s.key for s in self.sentences(self.bundle, "mulch.md") if s.text.startswith("Water early.")] self.assertEqual(2, len(set(water))) self.assertEqual([water[0].rsplit("-", 1)[0]] * 2, [k.rsplit("-", 1)[0] for k in water]) def test_headings_footnotes_and_code_blocks_are_not_sentences(self) -> None: texts = [s.text for s in self.sentences(self.bundle, "tomato.md")] self.assertFalse([t for t in texts if "History" in t or "garden.md, line" in t or t.startswith("mulch")]) self.assertIn("Plant after the last frost.[^f1]", texts) class PackSentencesTest(Fixture): def test_only_the_packs_fragment_sentences_are_listed(self) -> None: out = self.root / "s.json" code, _, _ = run_main(["sentences", "--accepted", str(self.accepted), "--pack", "1", "--bundle", str(self.bundle), "--out", str(out)]) self.assertEqual(0, code) pages = json.loads(out.read_text(encoding="utf-8"))["pages"] self.assertEqual({"tomato.md", "basil.md"}, set(pages)) self.assertEqual([self.key(self.bundle, "tomato.md", "Tomatoes"), self.key(self.bundle, "tomato.md", "A bed")], pages["tomato.md"]) def test_a_related_concepts_item_is_never_a_sentence_to_link(self) -> None: # A list item without a footnote is no claim; a title that happens to stand in a fragment must not list it. body = PAGES["tomato.md"].replace("[^f1]: garden.md", "## Related concepts\n\n- [Mulch](mulch.md)\n\n[^f1]: garden.md") (self.bundle / "tomato.md").write_text(body, encoding="utf-8") doc = dict(ACCEPTED, fragments=[*ACCEPTED["fragments"], {"pack": 1, "concept_id": "tomato", "text": "Mulch keeps the bed cool."}]) self.accepted.write_text(json.dumps(doc), encoding="utf-8") out = self.root / "s.json" code, _, _ = run_main(["sentences", "--accepted", str(self.accepted), "--pack", "1", "--bundle", str(self.bundle), "--out", str(out)]) self.assertEqual(0, code) self.assertIn("Mulch", [s.text for s in self.sentences(self.bundle, "tomato.md")]) # the item is a sentence self.assertEqual([self.key(self.bundle, "tomato.md", "Tomatoes"), self.key(self.bundle, "tomato.md", "A bed")], json.loads(out.read_text(encoding="utf-8"))["pages"]["tomato.md"]) def test_a_pack_with_no_sentence_fails(self) -> None: code, _, _ = run_main(["sentences", "--accepted", str(self.accepted), "--pack", "9", "--bundle", str(self.bundle), "--out", str(self.root / "s.json")]) self.assertEqual(1, code) class TaskTest(Fixture): def catalogue(self, ids: list[str]) -> Path: p = self.root / "catalogue.txt" p.write_text("\n".join(ids) + "\n", encoding="utf-8") return p def test_a_part_holds_the_contract_the_catalogue_and_only_the_listed_sentences(self) -> None: out = self.root / "tasks" sentences = self.root / "s.json" run_main(["sentences", "--accepted", str(self.accepted), "--pack", "1", "--bundle", str(self.bundle), "--out", str(sentences)]) code, _, _ = run_main(["task", str(self.bundle), "--sentences", str(sentences), "--catalogue", str(self.catalogue(["tomato", "basil"])), "--out", str(out)]) self.assertEqual(0, code) part = (out / "part-1.md").read_text(encoding="utf-8") self.assertIn(klink.CONTRACT, part) self.assertIn("tomato | Tomato", part) self.assertIn(self.key(self.bundle, "tomato.md", "A bed") + " | A bed beside basil suits them.[^f2]", part) self.assertNotIn("Stake them early", part) stats = json.loads((out / "parts.json").read_text(encoding="utf-8"))["parts"] self.assertEqual([{"part": 1, "file": "part-1.md", "pages": 2, "sentences": 3, "catalogue_chars": len("tomato | Tomato\nbasil | Basil\n"), "chars": len(part)}], stats) def test_parts_are_capped(self) -> None: pages = {"tomato.md": [s.key for s in self.sentences(self.bundle, "tomato.md")], "compost.md": [s.key for s in self.sentences(self.bundle, "compost.md")], "mulch.md": [s.key for s in self.sentences(self.bundle, "mulch.md")]} limit = len(klink.CONTRACT) + 400 parts = klink.render_parts(self.bundle, pages, ["soil"], "test", part_chars=limit) self.assertGreater(len(parts), 1) self.assertTrue(all(len(text) <= limit for text, _ in parts)) self.assertEqual(sum(len(v) for v in pages.values()), sum(stats["sentences"] for _, stats in parts)) def test_a_catalogue_alone_over_the_part_limit_cannot_run(self) -> None: # Plankontroll 05.10, addition 2: ~39 characters per concept, so ~1,500 concepts fill 60,000 characters alone. ids = [] for i in range(1, 1101): cid = f"garden-bed-number-{i:04d}" (self.bundle / f"{cid}.md").write_text(page(f"Garden bed number {i:04d} by the wall", [], "# Bed\n"), encoding="utf-8") ids.append(cid) sentences = self.root / "s.json" sentences.write_text(json.dumps({"pages": {"basil.md": [self.key(self.bundle, "basil.md", "Basil")]}})) code, _, err = run_main(["task", str(self.bundle), "--sentences", str(sentences), "--catalogue", str(self.catalogue(ids)), "--out", str(self.root / "tasks")]) self.assertEqual(2, code) self.assertIn("catalogue alone", err) self.assertIn("60000", err) self.assertFalse((self.root / "tasks" / "part-1.md").exists()) def test_task_refuses_existing_parts(self) -> None: sentences = self.root / "s.json" sentences.write_text(json.dumps({"pages": {"basil.md": [self.key(self.bundle, "basil.md", "Basil")]}})) args = ["task", str(self.bundle), "--sentences", str(sentences), "--catalogue", str(self.catalogue(["tomato"])), "--out", str(self.root / "tasks")] self.assertEqual(0, run_main(args)[0]) self.assertEqual(2, run_main(args)[0]) class AcceptTest(Fixture): def test_each_reject_reason(self) -> None: s = self.strip() winter = self.key(s, "compost.md", "Compost feeds") cases = { "malformed": {"page": "compost.md", "sentence": winter, "target": "soil"}, "sentence-missing": {"page": "compost.md", "sentence": "0000000000000000-0", "anchor": "soil", "target": "soil"}, "target-missing": {"page": "compost.md", "sentence": winter, "anchor": "soil", "target": "pepper"}, "self-link": {"page": "compost.md", "sentence": winter, "anchor": "Compost", "target": "compost"}, "no-footnote": {"page": "tomato.md", "sentence": self.key(s, "tomato.md", "Stake"), "anchor": "Stake", "target": "soil"}, "anchor-not-in-sentence": {"page": "compost.md", "sentence": winter, "anchor": "rain", "target": "soil"}, "anchor-in-code": {"page": "compost.md", "sentence": self.key(s, "compost.md", "Turn the `pile`"), "anchor": "pile", "target": "soil"}, } for reason, proposal in cases.items(): with self.subTest(reason=reason): code, doc = self.accept(self.propose([proposal]), s) self.assertEqual(0, code) self.assertEqual(1, doc["rejected"].get(reason), doc["rejected"]) self.assertEqual([], json.loads(self.links.read_text(encoding="utf-8"))["links"]) def test_part_of_a_word_is_not_an_anchor(self) -> None: s = self.strip() _, doc = self.accept(self.propose([{"page": "compost.md", "sentence": self.key(s, "compost.md", "Compost feeds"), "anchor": "oil", "target": "soil"}]), s) self.assertEqual({"anchor-not-in-sentence": 1}, doc["rejected"]) def test_duplicate_overlap_and_over_limit(self) -> None: s = self.strip() winter = self.key(s, "compost.md", "Compost feeds") def link(anchor: str, target: str) -> dict[str, str]: return {"page": "compost.md", "sentence": winter, "anchor": anchor, "target": target} _, doc = self.accept(self.propose([link("soil", "soil"), link("soil", "soil"), link("the soil", "mulch"), link("feeds", "basil"), link("winter", "mulch"), link("over", "tomato")]), s) self.assertEqual(3, len(doc["links"])) self.assertEqual({"duplicate": 1, "overlap": 1, "over-limit": 1}, doc["rejected"]) def test_a_semantic_anchor_that_is_not_the_targets_name_is_accepted_and_none_is_counted(self) -> None: s = self.strip() _, doc = self.accept(self.propose([{"page": "mulch.md", "sentence": self.key(s, "mulch.md", "Mulch keeps"), "anchor": "keeps the soil moist", "target": "compost"}], none=["basil"]), s) self.assertEqual([{"page": "mulch.md", "sentence": self.key(s, "mulch.md", "Mulch keeps"), "anchor": "keeps the soil moist", "at": len("Mulch "), "target": "compost.md"}], doc["links"]) self.assertEqual(1, doc["none_count"]) def test_accept_never_rewrites_a_record(self) -> None: s = self.strip() first = {"page": "basil.md", "sentence": self.key(s, "basil.md", "Basil"), "anchor": "tomatoes", "target": "tomato"} _, doc1 = self.accept(self.propose([first]), s) _, doc2 = self.accept(self.propose([{**first, "anchor": "grows"}], name="q.json"), s) self.assertEqual(doc1["links"][0], doc2["links"][0]) self.assertEqual({"duplicate": 1}, doc2["rejected"]) class PlaceTest(Fixture): def accept_all(self) -> Path: s = self.strip() self.accept(self.propose([ {"page": "basil.md", "sentence": self.key(s, "basil.md", "Basil"), "anchor": "tomatoes", "target": "tomato"}, {"page": "tomato.md", "sentence": self.key(s, "tomato.md", "A bed"), "anchor": "basil", "target": "basil"}, {"page": "mulch.md", "sentence": self.key(s, "mulch.md", "Mulch keeps"), "anchor": "keeps the soil moist", "target": "compost"}, {"page": "compost.md", "sentence": self.key(s, "compost.md", "Compost feeds"), "anchor": "winter", "target": "mulch"}, {"page": "compost.md", "sentence": self.key(s, "compost.md", "Rich soil"), "anchor": "Rich soil", "target": "soil"}, ]), s) return s def place(self, bundle: Path, out: Path, *extra: str) -> int: return run_main(["place", str(bundle), "--links", str(self.links), "--out", str(out), *extra])[0] def test_placed_fixture_passes_the_structure_rule(self) -> None: s = self.accept_all() out = self.root / "linked" self.assertEqual(0, self.place(s, out)) self.assertIn("Mulch [keeps the soil moist](compost.md) in summer.[^f1]", (out / "mulch.md").read_text(encoding="utf-8")) self.assertEqual([], audit.check_link_structure(audit.load_bundle(out, self.root))) def test_place_is_idempotent_and_reduces_links_first(self) -> None: s = self.accept_all() one, two = self.root / "one", self.root / "two" self.assertEqual(0, self.place(s, one)) self.assertEqual(0, self.place(one, two)) # placing on a placed bundle gives the same bytes for p in sorted(one.rglob("*.md")): self.assertEqual(p.read_bytes(), (two / p.relative_to(one)).read_bytes(), p.name) def test_place_refuses_to_overwrite_without_replace(self) -> None: s = self.accept_all() out = self.root / "linked" self.assertEqual(0, self.place(s, out)) self.assertEqual(2, self.place(s, out)) (out / "stray.md").write_text("old", encoding="utf-8") self.assertEqual(0, self.place(s, out, "--replace")) self.assertFalse((out / "stray.md").exists()) def test_a_stale_record_exits_1(self) -> None: s = self.accept_all() doc = json.loads(self.links.read_text(encoding="utf-8")) doc["links"].append({"page": "basil.md", "sentence": "0123456789abcdef-0", "anchor": "x", "at": 0, "target": "soil.md"}) self.links.write_text(json.dumps(doc), encoding="utf-8") self.assertEqual(1, self.place(s, self.root / "linked")) def test_a_record_whose_anchor_no_longer_stands_at_its_offset_is_stale(self) -> None: s = self.accept_all() doc = json.loads(self.links.read_text(encoding="utf-8")) doc["links"][0]["at"] += 1 self.links.write_text(json.dumps(doc), encoding="utf-8") self.assertEqual(1, self.place(s, self.root / "linked")) class NoClosingPassTest(unittest.TestCase): """The closing pass over pages without an inbound link was chosen away (direction point 3).""" def test_the_orphans_command_is_gone(self) -> None: with redirect_stderr(io.StringIO()): with self.assertRaises(SystemExit) as caught: klink.main(["orphans", "bundle", "--out", "out"]) self.assertEqual(2, caught.exception.code) self.assertFalse(hasattr(klink, "orphans")) def test_no_contract_mentions_a_closing_pass(self) -> None: root = Path(__file__).resolve().parents[1] texts = {"klink.CONTRACT": klink.CONTRACT, "klink docstring": klink.__doc__ or ""} for rel in ("agents/okf-wiki-linker.md", ".claude/agents/okf-wiki-linker.md"): texts[rel] = (root / rel).read_text(encoding="utf-8") for name, text in texts.items(): for phrase in ("closing pass", "closing-pass", "orphans"): with self.subTest(name=name, phrase=phrase): self.assertNotIn(phrase, text) class PassTest(Fixture): def test_pass_before_and_pass_after_chain_the_steps(self) -> None: s = self.strip() catalogue = self.root / "catalogue.txt" catalogue.write_text("tomato\nbasil\n", encoding="utf-8") pass_dir = self.root / "tasks" / "p1" code, out, _ = run_main(["pass-before", "--accepted", str(self.accepted), "--pack", "1", "--bundle", str(s), "--catalogue", str(catalogue), "--out", str(pass_dir)]) self.assertEqual(0, code) self.assertIn("parts 1", out) (pass_dir / "proposals-1.json").write_text(json.dumps({"links": [ {"page": "basil.md", "sentence": self.key(s, "basil.md", "Basil"), "anchor": "tomatoes", "target": "tomato"}], "none": ["tomato.md"]}), encoding="utf-8") transcripts = self.root / "transcripts" (transcripts / "s1" / "subagents").mkdir(parents=True) (transcripts / "s1.jsonl").write_text(json.dumps({"type": "assistant", "message": { "id": "m1", "stop_reason": "end_turn", "usage": {"input_tokens": 10, "output_tokens": 5}}}) + "\n") okter = self.root / "okter.txt" okter.write_text("s1 build\n", encoding="utf-8") argv = ["pass-after", "--pass-dir", str(pass_dir), "--bundle", str(s), "--links", str(self.links), "--linked", str(self.root / "linked"), "--sources", str(self.root), "--transcripts", str(transcripts), "--okter", str(okter), "--work", str(self.root), "--kost", str(self.root / "kost.json"), "--lines", "link,orchestration-build", "--unit", "passes", "--done", "1", "--total", "5"] code, out, _ = run_main([*argv, "--cap", "1000"]) self.assertEqual(0, code, out) self.assertIn("accepted 1", out) self.assertIn("none 1", out) self.assertIn("link rule: 1 of 5", out) self.assertIn("[tomatoes](tomato.md)", (self.root / "linked" / "basil.md").read_text(encoding="utf-8")) self.assertEqual(1, run_main([*argv, "--cap", "10"])[0]) # 15 x 5 x 1.1 is over 10: STOP class PassStopLineTest(Fixture): """Order 22 session A3: in the skill's chain the pass-after of pack N runs after the compiler of pack N+1, so the harvest holds that compiler's run. Measured in B2: 3,629,261 over 885 blocks (pack 1 alone) gave 20.4 M with the margin; the same cost over the blocks of packs 1 and 2 gives 13.4 M. Both sides of the stop line now cover the same packs: the blocks of every pack with a compiler run, and a run that cannot be tied to a logged pack is STOP.""" PACKS = {"schema": "okf-wiki/k-packs/1", "size": 5, "packs": [ {"pack": 1, "sources": ["garden.md"], "blocks": 10, "accepted": 3}, {"pack": 2, "sources": ["soil.md"], "blocks": 30}]} def agent(self, transcripts: Path, name: str, description: str, total: int) -> None: sub = transcripts / "s1" / "subagents" sub.mkdir(parents=True, exist_ok=True) (sub / f"agent-{name}.jsonl").write_text(json.dumps({"type": "assistant", "message": { "id": f"m-{name}", "stop_reason": "end_turn", "usage": {"input_tokens": total - 10, "output_tokens": 10}}}) + "\n", encoding="utf-8") (sub / f"agent-{name}.meta.json").write_text(json.dumps({"agentType": "x", "description": description})) def run_pass(self, runs: dict[str, int], cap: int, done: int = 10) -> tuple[int, str, str]: s = self.stripped if self.stripped.exists() else self.strip() pass_dir = self.root / "tasks" / "p1" if not pass_dir.exists(): self.assertEqual(0, run_main(["pass-before", "--accepted", str(self.accepted), "--pack", "1", "--bundle", str(s), "--out", str(pass_dir)])[0]) (pass_dir / "proposals-1.json").write_text(json.dumps({"links": [], "none": ["tomato.md"]})) transcripts = self.root / "transcripts" shutil.rmtree(transcripts, ignore_errors=True) (transcripts / "s1" / "subagents").mkdir(parents=True) (transcripts / "s1.jsonl").write_text(json.dumps({"type": "assistant", "message": { "id": "m1", "stop_reason": "end_turn", "usage": {"input_tokens": 10, "output_tokens": 5}}}) + "\n") for description, total in runs.items(): self.agent(transcripts, description.rsplit("-", 1)[-1] + str(total), description, total) (self.root / "okter.txt").write_text("s1 build\n", encoding="utf-8") packs = self.root / "packs.json" packs.write_text(json.dumps(self.PACKS), encoding="utf-8") return run_main([ "pass-after", "--pass-dir", str(pass_dir), "--bundle", str(s), "--links", str(self.links), "--linked", str(self.root / "linked"), "--sources", str(self.root), "--transcripts", str(transcripts), "--okter", str(self.root / "okter.txt"), "--work", str(self.root), "--kost", str(self.root / "kost.json"), "--lines", "build,link,orchestration-build", "--unit", "blocks", "--done", str(done), "--total", "100", "--blocks", str(packs), "--cap", str(cap)]) def stop_row(self) -> dict[str, Any]: row: dict[str, Any] = json.loads((self.root / "kost.json").read_text(encoding="utf-8"))["stops"][ "build,link,orchestration-build"] return row def test_the_next_packs_compiler_counts_with_its_blocks(self) -> None: # 15 + 100 + 300 + 50 = 465 over 10 + 30 blocks, x 100 / 40 x 1.1 = 1279; over pack 1 alone it would be 5115 runs = {"V1-r-pack-p1": 100, "V1-r-pack-p2": 300, "V1-r-link-p1": 50} code, out, err = self.run_pass(runs, cap=2000) self.assertEqual(0, code, out + err) self.assertIn("done: 40 of 100 blocks (packs 1, 2 with a compiler run)", out) self.assertEqual((465, 40, 1279), (self.stop_row()["measured"], self.stop_row()["done"], self.stop_row()["projected_with_margin"])) def test_the_stop_is_measured_cost_and_a_new_run_of_the_compiled_pack(self) -> None: # The operator 12.10.2026: measured cost plus a margin stops, the projection is reported only. Before the next # check (run-after 2) the model may run pack 2's compiler once more, so the next pack is pack 2 (30 blocks): # (465 + 465 x 30 / 40) x 1.1 = 896, where the projection says 1279. runs = {"V1-r-pack-p1": 100, "V1-r-pack-p2": 300, "V1-r-link-p1": 50} self.assertEqual(0, self.run_pass(runs, cap=896)[0]) self.assertEqual((30, 896, 1279), (self.stop_row().get("next"), self.stop_row().get("measured_next_with_margin"), self.stop_row()["projected_with_margin"])) self.assertEqual(1, self.run_pass(runs, cap=895)[0]) def test_with_characters_the_compiled_pack_s_share_is_by_its_characters(self) -> None: # Motor B17: 465 over the 1000 + 6000 characters of packs 1 and 2, the compiled pack 2 again: 465 x 6000 / 7000 # = 398.6; (465 + 398.6) x 1.1 = 950, where by blocks it is 896. runs = {"V1-r-pack-p1": 100, "V1-r-pack-p2": 300, "V1-r-link-p1": 50} packs = json.loads(json.dumps(self.PACKS)) packs["packs"][0]["block_chars"], packs["packs"][1]["block_chars"] = 1_000, 6_000 with mock.patch.object(self, "PACKS", packs): code, out, err = self.run_pass(runs, cap=950) self.assertEqual(0, code, out + err) row = self.stop_row() self.assertEqual(("measured-chars", 6_000, 950), (row.get("rule"), row.get("next_chars"), row.get("measured_next_with_margin"))) self.assertEqual(1, self.run_pass(runs, cap=949)[0]) def test_a_pack_built_in_an_earlier_ledger_costs_nothing_here_and_sets_no_rate(self) -> None: # Order 27 A3: pack 1 was built before (round 2's packs 1-8 for a variant), pack 2 is this ledger's. The next # pack's share comes from pack 2 alone: 15 + 300 + 50 = 365 over 30 blocks, next 30: (365 + 365) x 1.1 = 803; # over the 40 blocks of packs 1 and 2 it would be (365 + 365 x 30 / 40) x 1.1 = 703. runs = {"V1-r-pack-p2": 300, "V1-r-link-p1": 50} code, out, err = self.run_pass(runs, cap=803) self.assertEqual(0, code, out + err) self.assertIn("done: 40 of 100 blocks (packs 2 with a compiler run)", out) self.assertEqual((40, 30, 803), (self.stop_row()["done"], self.stop_row()["rate_blocks"], self.stop_row()["measured_next_with_margin"])) self.assertEqual(1, self.run_pass(runs, cap=802)[0]) def test_without_a_later_compiler_run_the_blocks_are_the_pass_packs(self) -> None: code, out, err = self.run_pass({"V1-r-pack-p1": 100, "V1-r-link-p1": 50}, cap=2000) self.assertEqual(0, code, out + err) self.assertIn("done: 10 of 100 blocks (packs 1 with a compiler run)", out) runs = {"V1-r-pack-p1": 100, "V1-r-link-p1": 50} # every compiled pack accepted: next 0, 165 x 1.1 = 182 self.assertEqual(0, self.run_pass(runs, cap=182)[0]) self.assertEqual(1, self.run_pass(runs, cap=181)[0]) def test_a_run_for_a_pack_the_log_lacks_is_stop(self) -> None: code, out, err = self.run_pass({"V1-r-pack-p1": 100, "V1-r-pack-p3": 30}, cap=10 ** 9) self.assertEqual(2, code, out) self.assertIn("pack 3", err) def test_a_run_tied_to_no_pack_is_stop(self) -> None: code, out, err = self.run_pass({"V1-r-pack-p1": 100, "V1-r-link-all": 30}, cap=10 ** 9) self.assertEqual(2, code, out) self.assertIn("V1-r-link-all", err) def test_done_must_be_the_blocks_of_the_packs_the_pass_covers(self) -> None: code, out, err = self.run_pass({"V1-r-pack-p1": 100, "V1-r-pack-p2": 300}, cap=10 ** 9, done=7) self.assertEqual(2, code, out) self.assertIn("--done 7", err) class IntervalTest(Fixture): """Order 20261005T182702Z (C1): one pass covers an interval of packs, so the orchestrator's turns do not grow with it.""" def before(self, bundle: Path, out: Path, pack: int, to: int | None = None) -> tuple[int, str]: argv = ["pass-before", "--accepted", str(self.accepted), "--pack", str(pack), "--bundle", str(bundle), "--out", str(out)] code, stdout, _ = run_main(argv + (["--to", str(to)] if to is not None else [])) return code, stdout def after(self, bundle: Path, pass_dir: Path, links: Path, done: int) -> tuple[int, str]: transcripts = self.root / "transcripts" if not transcripts.exists(): (transcripts / "s1" / "subagents").mkdir(parents=True) (transcripts / "s1.jsonl").write_text(json.dumps({"type": "assistant", "message": { "id": "m1", "stop_reason": "end_turn", "usage": {"input_tokens": 10, "output_tokens": 5}}}) + "\n") (self.root / "okter.txt").write_text("s1 build\n", encoding="utf-8") code, stdout, _ = run_main([ "pass-after", "--pass-dir", str(pass_dir), "--bundle", str(bundle), "--links", str(links), "--linked", str(links.with_suffix("")) + "-linked", "--sources", str(self.root), "--transcripts", str(transcripts), "--okter", str(self.root / "okter.txt"), "--work", str(self.root), "--kost", str(links.with_suffix(".kost.json")), "--lines", "link,orchestration-build", "--unit", "passes", "--done", str(done), "--total", "2", "--cap", "1000000"]) return code, stdout def proposals(self, s: Path, pass_dir: Path) -> None: (pass_dir / "p1" / "proposals-1.json").write_text(json.dumps({"links": [ {"page": "basil.md", "sentence": self.key(s, "basil.md", "Basil"), "anchor": "tomatoes", "target": "tomato"}], "none": ["tomato.md"]}), encoding="utf-8") (pass_dir / "p2" / "proposals-1.json").write_text(json.dumps({"links": [ {"page": "mulch.md", "sentence": self.key(s, "mulch.md", "Mulch"), "anchor": "the soil", "target": "compost"}, {"page": "compost.md", "sentence": self.key(s, "compost.md", "Compost feeds"), "anchor": "Compost", "target": "mulch"}], "none": []}), encoding="utf-8") def test_an_interval_writes_the_same_tasks_as_single_passes(self) -> None: s = self.strip() single, interval = self.root / "single", self.root / "interval" self.assertEqual(0, self.before(s, single / "p1", 1)[0]) self.assertEqual(0, self.before(s, single / "p2", 2)[0]) code, out = self.before(s, interval, 1, to=2) self.assertEqual(0, code, out) for rel in ("p1/sentences.json", "p1/parts.json", "p1/part-1.md", "p2/sentences.json", "p2/parts.json", "p2/part-1.md"): self.assertEqual((single / rel).read_bytes(), (interval / rel).read_bytes(), rel) self.assertIn(f"{interval / 'p1' / 'part-1.md'} -> {interval / 'p1' / 'proposals-1.json'}", out) self.assertIn(f"{interval / 'p2' / 'part-1.md'} -> {interval / 'p2' / 'proposals-1.json'}", out) def test_an_interval_gives_the_same_links_as_single_passes(self) -> None: s = self.strip() tasks = self.root / "tasks" self.assertEqual(0, self.before(s, tasks, 1, to=2)[0]) self.proposals(s, tasks) single, interval = self.root / "single.json", self.root / "interval.json" self.assertEqual(0, self.after(s, tasks / "p1", single, 1)[0]) self.assertEqual(0, self.after(s, tasks / "p2", single, 2)[0]) code, out = self.after(s, tasks, interval, 2) self.assertEqual(0, code, out) self.assertEqual(single.read_bytes(), interval.read_bytes()) self.assertEqual(3, json.loads(interval.read_text(encoding="utf-8"))["accepted"]) self.assertIn("accept p1: accepted 1", out) self.assertIn("accept p2: accepted 2", out) self.assertIn("accept: accepted 3", out) def test_the_orchestrator_runs_two_commands_whatever_the_interval(self) -> None: s = self.strip() for to in (1, 2): tasks = self.root / f"tasks-{to}" self.assertEqual(0, self.before(s, tasks, 1, to=to)[0]) parts = sorted(p.relative_to(tasks).as_posix() for p in tasks.rglob("part-*.md")) self.assertEqual([f"p{n}/part-1.md" for n in range(1, to + 1)], parts) (tasks / "p2").mkdir(exist_ok=True) self.proposals(s, tasks) if to == 1: shutil.rmtree(tasks / "p2") code, out = self.after(s, tasks, self.root / f"links-{to}.json", to) self.assertEqual(0, code, out) self.assertIn(f"accept: accepted {1 if to == 1 else 3}", out) def test_a_pack_directory_without_proposals_cannot_run(self) -> None: s = self.strip() tasks = self.root / "tasks" self.before(s, tasks, 1, to=2) (tasks / "p1" / "proposals-1.json").write_text(json.dumps({"links": [], "none": []}), encoding="utf-8") self.assertEqual(2, self.after(s, tasks, self.root / "links.json", 2)[0]) def test_pack_directories_are_taken_in_number_order(self) -> None: for name in ("p10", "p2", "p1", "other"): (self.root / "t" / name).mkdir(parents=True) self.assertEqual(["p1", "p2", "p10"], [d.name for d in klink.pack_dirs(self.root / "t")]) class CatalogueFilterTest(Fixture): """Order 20261005T182702Z (C2): each pack's task gets only candidate targets, within a character budget.""" def accepted_doc(self, packs: dict[int, list[str]]) -> dict[str, Any]: return {"fragments": [{"pack": p, "concept_id": cid, "text": "x"} for p, ids in packs.items() for cid in ids]} def test_the_packs_own_concepts_come_first_then_recent_packs_then_the_most_cited(self) -> None: pages = klink.read_pages(self.bundle) doc = self.accepted_doc({1: ["tomato", "basil"], 2: ["compost"], 4: ["soil"], 5: ["mulch"]}) pool = ["basil", "compost", "mulch", "soil", "tomato"] # mulch is the pack's own; soil is from pack 4, inside the recent window; compost cites two source files. self.assertEqual(["mulch", "soil", "compost", "basil", "tomato"], klink.filter_catalogue(doc, 5, pool, pages, budget=10_000)) budget = len(klink.catalogue_text(["mulch", "soil", "compost"], pages)) self.assertEqual(["mulch", "soil", "compost"], klink.filter_catalogue(doc, 5, pool, pages, budget=budget)) def test_the_main_pages_are_always_in_the_catalogue_first_and_then_the_rest_by_rank(self) -> None: # Order 28 A3: modelled without a model before the rest of collection 1, a late pack saw 31 of 195 main pages # with the old rule; main pages are the homes (criterion 6), so they come first, each kept in its rank's order. pages = klink.read_pages(self.bundle) doc = self.accepted_doc({1: ["tomato", "basil"], 2: ["compost"], 4: ["soil"], 5: ["mulch"]}) doc["main_pages"] = [{"source": "garden.md", "concept_id": "basil", "pack": 1}, {"source": "soil.md", "concept_id": "soil", "pack": 4}, {"source": "gone.md", "concept_id": "ghost", "pack": 2}] # not in the pool: left out pool = ["basil", "compost", "mulch", "soil", "tomato"] self.assertEqual(["soil", "basil", "mulch", "compost", "tomato"], klink.filter_catalogue(doc, 5, pool, pages, budget=10_000)) budget = len(klink.catalogue_text(["soil", "basil", "mulch"], pages)) self.assertEqual(["soil", "basil", "mulch"], klink.filter_catalogue(doc, 5, pool, pages, budget=budget)) def test_a_long_page_splits_over_parts_whatever_the_limit_and_its_continued_heading(self) -> None: # Order 28 A8: the dry run stopped on pack 26 (one page of 2,011 sentences) with "one sentence does not fit": # the check before a line used the page's heading, the part it filled carried "(continued)", 12 longer lines = [f"- k{i:04d} | Sentence number {i:04d} of a long page.\n" for i in range(60)] section = klink.Section("long.md", lines, "long.md") one = len(klink.part_text("pack 1", "", [klink.Section("long.md", lines[:1], "long.md (continued)")])) for limit in range(one + klink.PART_HEADER_ROOM, one + klink.PART_HEADER_ROOM + 400): with self.subTest(limit=limit): parts = klink.render_sections("pack 1", [], [section], {}, limit) self.assertTrue(all(len(text) <= limit for text, _ in parts)) self.assertEqual(60, sum(stats["sentences"] for _, stats in parts)) def test_the_catalogue_has_room_for_the_main_pages_and_the_far_concepts_of_the_rest(self) -> None: # Order 28 A3: with the main pages first, 32,000 characters keep at least 205 far concepts in every pack of the # model (G's pack 10 showed 179; the model put 25 too many there); 24,000 left three packs short self.assertEqual(32_000, klink.CATALOGUE_CHARS) def test_without_a_catalogue_file_the_pool_is_the_concepts_of_this_and_earlier_packs(self) -> None: s = self.strip() self.assertEqual(0, run_main(["pass-before", "--accepted", str(self.accepted), "--pack", "1", "--bundle", str(s), "--out", str(self.root / "t1")])[0]) part = (self.root / "t1" / "part-1.md").read_text(encoding="utf-8") self.assertIn("tomato | Tomato", part) self.assertNotIn("compost | Compost", part) stats = json.loads((self.root / "t1" / "parts.json").read_text(encoding="utf-8")) self.assertEqual({"concepts": 2, "pool": 2}, stats["catalogue"]) def test_a_part_stays_under_the_limit_with_a_catalogue_of_6700_concepts(self) -> None: # Order C2: collection 1 may reach ~6,700 concepts (brief Q2); unfiltered, the catalogue alone is ~4x the limit. bundle = self.root / "big" bundle.mkdir() fragments = [] for i in range(6700): cid, pack = f"raised-garden-bed-number-{i:04d}", i // 56 + 1 body = f"# Bed {i:04d}\n\nRaised bed number {i:04d} holds beans and peas all summer.[^f1]\n\n[^f1]: garden.md, line 2\n" (bundle / f"{cid}.md").write_text(page(f"Raised garden bed number {i:04d}", [("f1", GARDEN, 2, "Beans")], body), encoding="utf-8") fragments.append({"pack": pack, "concept_id": cid, "text": f"Raised bed number {i:04d} holds beans and peas all summer."}) accepted = self.root / "big-accepted.json" accepted.write_text(json.dumps({"fragments": fragments}), encoding="utf-8") last = fragments[-1]["pack"] out = self.root / "big-tasks" code, stdout, err = run_main(["pass-before", "--accepted", str(accepted), "--pack", str(last), "--bundle", str(bundle), "--out", str(out)]) self.assertEqual(0, code, err) stats = json.loads((out / "parts.json").read_text(encoding="utf-8")) self.assertEqual(6700, stats["catalogue"]["pool"]) for p in stats["parts"]: self.assertLessEqual(p["chars"], klink.PART_CHARS) self.assertLessEqual(p["catalogue_chars"], klink.CATALOGUE_CHARS) part = (out / "part-1.md").read_text(encoding="utf-8") own = [f["concept_id"] for f in fragments if f["pack"] == last] self.assertTrue(all(f"{cid} | " in part for cid in own)) class GuardTest(Fixture): FINDINGS = {"findings": [ {"check": "no-main-page-link", "group": "links", "file": "mulch.md", "line": None, "message": "m"}, {"check": "main-page-missing", "group": "links", "file": "kilde/soil.md", "line": None, "message": "m"}, {"check": "main-page-missing", "group": "links", "file": "", "line": None, "message": "main-topic source /kilde/garden.md has no main page"}, {"check": "broken-link", "group": "links", "file": "tomato.md", "line": 3, "message": "m"}, {"check": "no-main-page-link", "group": "links", "file": "mulch.md", "line": None, "message": "again"}, ], "summary": {}, "link_rule": {}} def test_homeless_takes_the_pages_and_sources_the_auditor_names_and_nothing_else(self) -> None: pages, missing = klink.homeless(self.FINDINGS) self.assertEqual(pages, ["mulch.md"]) self.assertEqual(missing, ["kilde/garden.md", "kilde/soil.md"]) # the K1 path, with or without the leading / self.assertEqual(klink.GUARDED, frozenset({"no-main-page-link", "main-page-missing"})) unnamed = {"findings": [{"check": "main-page-missing", "group": "links", "file": "", "line": None, "message": "a source has no main page"}]} with self.assertRaises(RunError): klink.homeless(unnamed) def test_the_candidates_for_a_source_are_the_pages_that_cite_it(self) -> None: got = klink.guard_candidates(self.bundle, ["kilde/soil.md", "kilde/none.md"]) self.assertEqual(got, {"kilde/soil.md": ["compost", "soil"], "kilde/none.md": []}) def test_the_task_holds_the_contract_the_catalogue_each_page_and_each_source_with_its_candidates(self) -> None: parts = klink.guard_parts(self.bundle, ["mulch.md"], ["kilde/soil.md"], ["tomato", "basil"], "pack 2") self.assertEqual(len(parts), 1) text = parts[0] self.assertIn(klink.GUARD_CONTRACT, text) catalogue = text.split("## Catalogue (main pages)", 1)[1].split("\n## ", 1)[0] self.assertIn("- tomato | Tomato", catalogue) self.assertIn("- basil | Basil", catalogue) self.assertNotIn("mulch", catalogue) self.assertIn("- mulch | Mulch | Mulch in the garden.", text.split("## Pages without a home", 1)[1]) sources = text.split("## Sources without a main page", 1)[1] self.assertIn("### kilde/soil.md", sources) self.assertIn("- compost | Compost", sources) self.assertIn("- soil | Soil", sources) def test_a_long_task_is_split_into_parts_that_each_carry_the_contract_and_the_catalogue(self) -> None: pages = sorted(p for p in PAGES if p not in ("index.md", "log.md")) parts = klink.guard_parts(self.bundle, pages * 40, [], ["tomato"], "pack 9", part_chars=4000) self.assertGreater(len(parts), 1) for text in parts: self.assertLessEqual(len(text), 4000) self.assertIn(klink.GUARD_CONTRACT, text) self.assertIn("- tomato | Tomato", text) def test_the_answer_is_checked_by_code(self) -> None: answer = {"homes": [{"page": "mulch", "home": "tomato"}, # kept {"page": "mulch.md", "home": "tomato"}, # duplicate: mulch has its answer {"page": "rose", "home": "tomato"}, # page-not-asked {"page": "soil", "home": "soil"}, # self-home {"page": "soil", "home": "rose"}, # home-not-in-catalogue {"page": "soil", "home": "compost"}, # kept: compost is named a main page below ["x"]], # malformed "none": ["compost", "rose"], # compost kept; rose page-not-asked "main_pages": [{"source": "kilde/soil.md", "page": "tomato"}, # page-not-a-candidate {"source": "/kilde/soil.md", "page": "compost"}, # kept {"source": "kilde/soil.md", "page": "soil"}, # duplicate: the source has its answer {"source": "kilde/garden.md", "page": "basil"}]} # source-not-asked got = klink.read_guard(answer, ["mulch.md", "compost.md", "soil.md", "basil.md"], ["kilde/soil.md"], ["tomato"], klink.guard_candidates(self.bundle, ["kilde/soil.md"])) self.assertEqual(got.homes, [("mulch", "tomato"), ("soil", "compost")]) self.assertEqual(got.main_pages, [("kilde/soil.md", "compost")]) self.assertEqual(got.none, ["compost"]) self.assertEqual(got.unanswered, ["basil"]) self.assertEqual(dict(got.rejected), {"duplicate": 2, "page-not-asked": 2, "self-home": 1, "home-not-in-catalogue": 1, "malformed": 1, "page-not-a-candidate": 1, "source-not-asked": 1}) def test_none_is_kept_for_a_page_without_a_home(self) -> None: got = klink.read_guard({"homes": [], "none": ["mulch"], "main_pages": []}, ["mulch.md"], [], ["tomato"], {}) self.assertEqual((got.homes, got.none, got.unanswered), ([], ["mulch"], [])) class CodeBracketTest(unittest.TestCase): """A [ inside a code span opens no link (CommonMark 6.1), so reducing a link keeps the code span whole.""" SENTENCE = "Press `[` to mark a row, or see [the shed](shed.md)." def test_reduce_links_keeps_a_bracket_in_code(self) -> None: self.assertEqual(("Press `[` to mark a row, or see the shed.", 1), klink.reduce_links(self.SENTENCE)) def test_a_linked_sentence_has_the_key_of_its_unlinked_text(self) -> None: self.assertEqual("Press `[` to mark a row, or see the shed.", klink.key_text(self.SENTENCE)) def test_a_link_inside_code_is_still_reduced(self) -> None: self.assertEqual(("Write `the shed` here.", 1), klink.reduce_links("Write `[the shed](shed.md)` here.")) class AgentTest(unittest.TestCase): def test_the_two_agent_copies_are_identical_and_carry_the_contract(self) -> None: shipped = (ROOT / "agents" / "okf-wiki-linker.md").read_text(encoding="utf-8") self.assertEqual(shipped, (ROOT / ".claude" / "agents" / "okf-wiki-linker.md").read_text(encoding="utf-8")) self.assertIn(klink.CONTRACT, shipped) self.assertIn(klink.GUARD_CONTRACT, shipped) # the guard's home task runs on the linker (order 10) self.assertIn("tools: Read, Write", shipped) class NoModelTest(unittest.TestCase): def test_tool_imports_no_network_or_model_client(self) -> None: source = (ROOT / "okfwiki" / "klink.py").read_text(encoding="utf-8") for banned in ("anthropic", "openai", "urllib", "http.client", "requests", "subprocess", "socket"): self.assertNotIn(f"import {banned}", source) if __name__ == "__main__": unittest.main()