xrefkit 0.4.7__tar.gz → 0.4.9__tar.gz

xrefkit-0.4.9/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: xrefkit
+Version: 0.4.9
+Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
+Author: synthaicode
+License: MIT License
+        
+        Copyright (c) 2026 Ritu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.2
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Requires-Dist: uvicorn>=0.30; extra == "mcp"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Dynamic: license-file
+
+# XRefKit
+
+XRefKit is a framework for making AI-assisted work repeatable, reviewable, and
+handoff-ready.
+
+It helps teams turn domain procedures and knowledge into work that can be
+performed with explicit evidence, human judgment, and completion checks.
+
+## Why XRefKit?
+
+Using AI for real work creates recurring operating problems:
+
+![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+- the AI can act from incomplete context or unsupported guesses
+- procedures, domain facts, and judgment criteria get mixed together in prompts
+- execution, checking, and handoff collapse into one opaque step
+- work becomes hard to continue across agents, humans, or sessions
+- outputs may lack evidence, closure discipline, or auditability
+
+XRefKit provides a repository and runtime model for addressing these problems.
+
+## What it provides
+
+- **Skills** — reusable procedures for a defined kind of work
+- **Knowledge** — source-backed domain facts and local rules
+- **Workflow protocol** — recorded progress, deterministic verification, and
+  closure checks
+- **Evidence and handoffs** — outputs, judgments, concerns, and decisions that
+  remain reviewable after the work is done
+- **Skill Run Dashboard** — inspect Skill execution status, referenced XIDs,
+  evidence, judgments, concerns, and handoffs to improve the auditability of
+  results
+- **XIDs** — stable references for connecting procedures, knowledge, and
+  supporting documents
+
+The package includes the resolver, Skill runtime, workflow controls, client
+tools, and an optional MCP adapter.
+
+The [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
+helps people trace how a Skill run used its referenced XIDs and recorded its
+evidence before accepting or handing off the result.
+
+## Quick start
+
+XRefKit requires Python 3.11 or later.
+
+```powershell
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+For local development:
+
+```powershell
+python -m pip install -e .
+xrefkit init
+```
+
+For the optional MCP server:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+## Where to go next
+
+- [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
+- [Understand the workflow protocol](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
+- [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60)
+- [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
+- [Author a Skill with xref](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B)
+- [Browse the complete documentation index](docs/000_index.md#xid-56DD6EB68343)
+
+## Security
+
+XRefKit does not require provider API keys to explore or install the package.
+Do not commit secrets, API keys, access tokens, `.env` files, or provider
+credentials. Authenticate external AI tools through their official provider
+mechanisms.

xrefkit-0.4.9/README.md

@@ -0,0 +1,82 @@
+# XRefKit
+
+XRefKit is a framework for making AI-assisted work repeatable, reviewable, and
+handoff-ready.
+
+It helps teams turn domain procedures and knowledge into work that can be
+performed with explicit evidence, human judgment, and completion checks.
+
+## Why XRefKit?
+
+Using AI for real work creates recurring operating problems:
+
+![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+- the AI can act from incomplete context or unsupported guesses
+- procedures, domain facts, and judgment criteria get mixed together in prompts
+- execution, checking, and handoff collapse into one opaque step
+- work becomes hard to continue across agents, humans, or sessions
+- outputs may lack evidence, closure discipline, or auditability
+
+XRefKit provides a repository and runtime model for addressing these problems.
+
+## What it provides
+
+- **Skills** — reusable procedures for a defined kind of work
+- **Knowledge** — source-backed domain facts and local rules
+- **Workflow protocol** — recorded progress, deterministic verification, and
+  closure checks
+- **Evidence and handoffs** — outputs, judgments, concerns, and decisions that
+  remain reviewable after the work is done
+- **Skill Run Dashboard** — inspect Skill execution status, referenced XIDs,
+  evidence, judgments, concerns, and handoffs to improve the auditability of
+  results
+- **XIDs** — stable references for connecting procedures, knowledge, and
+  supporting documents
+
+The package includes the resolver, Skill runtime, workflow controls, client
+tools, and an optional MCP adapter.
+
+The [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
+helps people trace how a Skill run used its referenced XIDs and recorded its
+evidence before accepting or handing off the result.
+
+## Quick start
+
+XRefKit requires Python 3.11 or later.
+
+```powershell
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+For local development:
+
+```powershell
+python -m pip install -e .
+xrefkit init
+```
+
+For the optional MCP server:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+## Where to go next
+
+- [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
+- [Understand the workflow protocol](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
+- [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60)
+- [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
+- [Author a Skill with xref](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B)
+- [Browse the complete documentation index](docs/000_index.md#xid-56DD6EB68343)
+
+## Security
+
+XRefKit does not require provider API keys to explore or install the package.
+Do not commit secrets, API keys, access tokens, `.env` files, or provider
+credentials. Authenticate external AI tools through their official provider
+mechanisms.

{xrefkit-0.4.7 → xrefkit-0.4.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.7"
+version = "0.4.9"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

xrefkit-0.4.9/tests/test_brownfield_file_editing_protocol.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_brownfield_file_editing_protocol_is_in_canonical_and_packaged_skill() -> None:
+    canonical = (ROOT / "skills" / "brownfield-workflow" / "SKILL.md").read_text(encoding="utf-8")
+    packaged = (
+        ROOT / "packages" / "xrefkit-skills-brownfield" / "src" / "xrefkit_skills_brownfield"
+        / "skills" / "brownfield_workflow" / "entry.md"
+    ).read_text(encoding="utf-8")
+
+    for keyword in (
+        "encoding",
+        "BOM",
+        "newline",
+        "Unicode",
+        "strict",
+        "after_bytes",
+        "mojibake",
+        "concurrency",
+        "revision token",
+        "compare-and-swap",
+        "abort",
+        "atomically",
+        "specification",
+        "semantic",
+        "authoritative",
+        "hypothesis",
+        "semantic_alignment",
+        "Historical conflict investigation",
+        "bounded",
+        "Git",
+        "uncommitted",
+        "newest",
+        "Uncommitted-file policy",
+        "pre_existing_human_or_unknown",
+        "ai_owned_current_work",
+        "mixed_or_overlapping",
+        "untracked",
+        "stash",
+        "New-file extension conformity",
+        "peer",
+        "companion files",
+        "extension-specific",
+        "cluster",
+        "majority",
+        "same directory",
+        "confidence",
+        "weak margin",
+        "repository-wide fallback",
+    ):
+        assert keyword in canonical
+        assert keyword in packaged

{xrefkit-0.4.7 → xrefkit-0.4.9}/tests/test_dashboard.py

@@ -241,6 +241,149 @@ class DashboardTests(unittest.TestCase):
             self.assertEqual(1, payload["summary"]["runs"])
             self.assertEqual("sample_skill", payload["runs"][0]["skill_id"])
 
+    def test_dashboard_exposes_recovery_trace(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            run_log = self._write_closed_run(root)
+            common = [
+                "workflow",
+                "recovery",
+                "--log",
+                str(run_log),
+                "--recovery-id",
+                "REC-001",
+                "--resume-location",
+                "after reconcile",
+                "--reason",
+                "child status was not yet projected",
+                "--next-action",
+                "confirm and rerun reconcile",
+            ]
+            self._run_main([*common, "--status", "proposed"])
+            self._run_main([*common, "--status", "confirmed", "--reviewer", "human@example.test"])
+
+            payload = build_payload(root, root / "work" / "sessions")
+            self.assertEqual(2, payload["summary"]["recoveries"])
+            self.assertEqual(
+                ["proposed", "confirmed"],
+                [item["status"] for item in payload["recoveries"]],
+            )
+            html = _html_page(payload)
+            self.assertIn('data-panel="recovery"', html)
+            self.assertIn('id="recovery"', html)
+            self.assertIn("Resume location", html)
+            self.assertIn("after reconcile", html)
+            self.assertIn("human@example.test", html)
+            self.assertIn("Executable action", html)
+            self.assertIn("Verification", html)
+            self.assertIn("Max attempts", html)
+
+    def test_dashboard_aggregates_runs_by_prompt_flow(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            first = root / "work" / "sessions" / "root.md"
+            second = root / "work" / "sessions" / "child.md"
+            for out, run_id, parent, work_item in (
+                (first, "11111111-1111-4111-8111-111111111111", None, None),
+                (second, "22222222-2222-4222-8222-222222222222", "11111111-1111-4111-8111-111111111111", "WI-002"),
+            ):
+                args = [
+                    "workflow", "run", "--task", "Flow node", "--out", str(out),
+                    "--run-id", run_id, "--flow-id", "FLOW-001",
+                    "--root-run-id", "11111111-1111-4111-8111-111111111111",
+                    "--use-default-completion-conditions",
+                ]
+                if parent:
+                    args.extend(["--parent-run-id", parent, "--work-item-id", work_item])
+                self._run_main(args)
+
+            payload = build_payload(root, root / "work" / "sessions")
+            assert payload["summary"]["flows"] == 1
+            flow = payload["flows"][0]
+            assert flow["flow_id"] == "FLOW-001"
+            assert flow["root_run_id"] == "11111111-1111-4111-8111-111111111111"
+            assert flow["state"] == "blocked"
+            assert set(flow["run_ids"]) == {
+                "11111111-1111-4111-8111-111111111111",
+                "22222222-2222-4222-8222-222222222222",
+            }
+            child = next(run for run in payload["runs"] if run["run_id"] == "22222222-2222-4222-8222-222222222222")
+            assert child["parent_run_id"] == "11111111-1111-4111-8111-111111111111"
+            assert child["work_item_id"] == "WI-002"
+
+    def test_workflow_delegate_starts_child_skill_and_records_parent_flow_trace(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._write_valid_skill(root)
+            parent = root / "work" / "sessions" / "parent.md"
+            child = root / "work" / "sessions" / "child.md"
+            self._run_main([
+                "workflow", "run", "--task", "Delegate one item", "--out", str(parent),
+                "--run-id", "11111111-1111-4111-8111-111111111111",
+                "--flow-id", "FLOW-002", "--use-default-completion-conditions",
+            ])
+            self._run_main([
+                "workflow", "delegate", "--root", str(root), "--parent-log", str(parent), "--meta", "skills/sample/meta.md",
+                "--task", "Execute delegated item", "--out", str(child),
+                "--run-id", "22222222-2222-4222-8222-222222222222", "--work-item-id", "WI-002",
+            ])
+            parent_text = parent.read_text(encoding="utf-8")
+            child_text = child.read_text(encoding="utf-8")
+            assert '"event":"child_run.started"' in parent_text
+            assert "- flow_id: `FLOW-002`" in child_text
+            assert "- parent_run_id: `11111111-1111-4111-8111-111111111111`" in child_text
+            assert "- work_item_id: `WI-002`" in child_text
+
+    def test_prompt_flow_supports_multiple_delegated_work_items(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._write_valid_skill(root)
+            parent = root / "work" / "sessions" / "parent.md"
+            children = [root / "work" / "sessions" / "child-a.md", root / "work" / "sessions" / "child-b.md"]
+            self._run_main([
+                "workflow", "run", "--task", "Mixed prompt", "--out", str(parent),
+                "--run-id", "11111111-1111-4111-8111-111111111111", "--flow-id", "FLOW-MULTI",
+                "--use-default-completion-conditions",
+            ])
+            for index, child in enumerate(children, start=1):
+                self._run_main([
+                    "workflow", "delegate", "--root", str(root), "--parent-log", str(parent),
+                    "--meta", "skills/sample/meta.md", "--task", f"Execute item {index}",
+                    "--out", str(child), "--run-id", f"{index + 1:08d}-2222-4222-8222-222222222222",
+                    "--work-item-id", f"WI-00{index}",
+                ])
+
+            payload = build_payload(root, root / "work" / "sessions")
+            flow = next(flow for flow in payload["flows"] if flow["flow_id"] == "FLOW-MULTI")
+            assert len(flow["run_ids"]) == 3
+            parent_run = next(run for run in flow["runs"] if run["run_id"] == "11111111-1111-4111-8111-111111111111")
+            assert len([event for event in parent_run["observation_events"] if event.get("event") == "child_run.started"]) == 2
+            assert {run["work_item_id"] for run in flow["runs"] if run["parent_run_id"]} == {"WI-001", "WI-002"}
+
+    def test_quality_review_routes_selected_skill_and_starts_child(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._write_valid_skill(root)
+            parent = root / "work" / "sessions" / "parent.md"
+            child = root / "work" / "sessions" / "quality.md"
+            self._run_main([
+                "workflow", "run", "--task", "Review flow", "--out", str(parent),
+                "--run-id", "11111111-1111-4111-8111-111111111111",
+                "--flow-id", "FLOW-QUALITY", "--use-default-completion-conditions",
+            ])
+            self._run_main([
+                "workflow", "quality-review", "--root", str(root), "--parent-log", str(parent),
+                "--meta", "skills/sample/meta.md", "--selected-skill", "sample_skill",
+                "--candidate", "sample_skill", "--reason", "The output requires the selected review capability",
+                "--task", "Review the output", "--out", str(child), "--work-item-id", "WI-001",
+            ])
+            parent_text = parent.read_text(encoding="utf-8")
+            child_text = child.read_text(encoding="utf-8")
+            assert '"selection_mode":"quality_review"' in parent_text
+            assert '"event":"child_run.started"' in parent_text
+            assert "- flow_id: `FLOW-QUALITY`" in child_text
+            assert "- work_item_id: `WI-001`" in child_text
+
     def test_dashboard_clears_missing_information_when_observability_is_recorded(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:
             root = Path(tmp)
@@ -403,6 +546,7 @@ class DashboardTests(unittest.TestCase):
             html = _html_page(build_payload(root, root / "work" / "sessions"))
 
             self.assertIn('data-panel="overview"', html)
+            self.assertIn('data-panel="flows"', html)
             self.assertIn('data-panel="attention"', html)
             self.assertIn('data-panel="closure"', html)
             self.assertIn('data-panel="evidence"', html)
@@ -411,6 +555,15 @@ class DashboardTests(unittest.TestCase):
             self.assertIn('data-panel="analysis"', html)
             self.assertIn('data-panel="missing-information"', html)
             self.assertIn('id="overview"', html)
+            self.assertIn('id="flows"', html)
+            self.assertIn("Execution tree", html)
+            self.assertIn("Flow details", html)
+            self.assertIn("Work Item", html)
+            self.assertIn("Minimum intake", html)
+            self.assertIn("State", html)
+            self.assertIn("Execution records", html)
+            self.assertIn("Activity", html)
+            self.assertIn("Evidence and concerns", html)
             self.assertIn('id="attention"', html)
             self.assertIn('id="closure"', html)
             self.assertIn('id="evidence"', html)

xrefkit-0.4.9/tests/test_host_precheck.py

@@ -0,0 +1,49 @@
+import json
+from pathlib import Path
+
+from xrefkit.host_precheck import build_precheck_report
+from xrefkit.__main__ import main
+
+
+def _spec(**overrides):
+    value = {
+        "host": "Codex Desktop 1.2",
+        "extension": "XRefKit extension 0.4.8",
+        "transcript_reference": "human-run/transcript-001",
+        "baseline": {"skill": "brownfield_workflow", "result": "managed"},
+        "observed": {"skill": "brownfield_workflow", "result": "managed"},
+        "evidence": {"bootstrap": True, "discovery": True, "route_selection": True},
+        "catalog": "available",
+        "intent": "clear",
+    }
+    value.update(overrides)
+    return value
+
+
+def test_precheck_passes_only_with_observable_managed_route_evidence():
+    report = build_precheck_report(_spec())
+    assert report["schema"] == "xrefkit.host_compatibility_precheck/v1"
+    assert report["assessment"]["status"] == "pass"
+    assert "private model reasoning" in report["unobservable"]
+
+
+def test_precheck_blocks_generic_preselection_without_claiming_override():
+    report = build_precheck_report(_spec(generic_preselection=True))
+    assert report["assessment"]["status"] == "blocked"
+    assert "explicit XRefKit entrypoint" in report["assessment"]["next_action"]
+    assert any("whether XRefKit overrode" in item for item in report["unobservable"])
+
+
+def test_precheck_distinguishes_missing_catalog_and_ambiguous_intent():
+    assert build_precheck_report(_spec(catalog="unavailable"))["assessment"]["status"] == "blocked"
+    assert build_precheck_report(_spec(intent="ambiguous"))["assessment"]["status"] == "needs_human_confirmation"
+
+
+def test_precheck_cli_writes_repeatable_json_report(tmp_path: Path, capsys):
+    source = tmp_path / "input.json"
+    output = tmp_path / "report.json"
+    source.write_text(json.dumps(_spec()), encoding="utf-8")
+    assert main(["host", "precheck", "--input", str(source), "--out", str(output)]) == 0
+    report = json.loads(output.read_text(encoding="utf-8"))
+    assert report["assessment"]["status"] == "pass"
+    assert json.loads(capsys.readouterr().out)["schema"] == report["schema"]

xrefkit-0.4.9/tests/test_human_evaluation.py

@@ -0,0 +1,93 @@
+import contextlib
+import io
+from pathlib import Path
+
+from xrefkit.__main__ import main
+
+
+def _run(root: Path, *args: str) -> int:
+    with contextlib.redirect_stdout(io.StringIO()):
+        argv = list(args)
+        if argv[:2] == ["workflow", "run"]:
+            argv.extend(["--root", str(root)])
+        return main(argv)
+
+
+def _closed_run(tmp_path: Path) -> Path:
+    log = tmp_path / "work" / "sessions" / "preceding.md"
+    assert _run(
+        tmp_path,
+        "workflow", "run", "--task", "Produce a bounded output", "--out", str(log),
+        "--use-default-completion-conditions",
+    ) == 0
+    assert _run(
+        tmp_path, "skill", "workitem", "--log", str(log), "--item", "WI-001",
+        "--text", "Produce output", "--completion-criterion", "output is recorded",
+        "--status", "done", "--role", "instruction:executor",
+    ) == 0
+    for artifact_id, kind, target, role in (
+        ("OUT-001", "output", "output.md", "instruction:executor"),
+        ("EVD-001", "evidence", "test command passed", "instruction:checker"),
+    ):
+        assert _run(
+            tmp_path, "skill", "artifact", "--log", str(log), "--artifact", artifact_id,
+            "--kind", kind, "--target", target, "--item", "WI-001", "--status", "done",
+            "--role", role,
+        ) == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(log), "--phase", "execution", "--status", "done", "--role", "instruction:executor") == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(log), "--phase", "handoff", "--status", "done", "--role", "instruction:handoff_owner") == 0
+    assert _run(tmp_path, "skill", "verify", "--log", str(log)) == 0
+    assert _run(tmp_path, "skill", "close", "--log", str(log)) == 0
+    return log
+
+
+def test_human_evaluation_is_optional_and_scoped(tmp_path: Path) -> None:
+    log = _closed_run(tmp_path)
+    assert _run(
+        tmp_path, "skill", "evaluate", "--log", str(log),
+        "--decision", "accepted_with_conditions",
+        "--classification", "correction",
+        "--next-handling", "repair_previous_run",
+        "--purpose-fit", "The overall purpose remains valid",
+        "--verified", "WI-001 and EVD-001",
+        "--uncertainty", "target B source is not snapshotted",
+        "--scope-finding", "WI-A|accepted|Target A is acceptable",
+        "--scope-finding", "WI-B|correction|Target B needs repair",
+        "--scope-link", "WI-B|EVD-B",
+        "--context-ref", "criteria:v1",
+        "--comparability", "gap",
+        "--comparability-gap", "target B source snapshot is unavailable",
+        "--evaluated-at", "2026-08-19T01:02:03Z",
+        "--proposed-classification", "continuation",
+    ) == 0
+    text = log.read_text(encoding="utf-8")
+    assert '"event":"human.evaluation"' in text
+    assert '"classification":"correction"' in text
+    assert '"preceding_run_id"' in text
+    assert '"target":"WI-B"' in text
+    assert '"linked_targets":["EVD-B"]' in text
+    assert '"comparability":"gap"' in text
+    assert '"classification_source":"human_confirmed"' in text
+
+
+def test_human_evaluation_does_not_accept_an_open_run(tmp_path: Path) -> None:
+    log = tmp_path / "work" / "sessions" / "open.md"
+    assert _run(
+        tmp_path, "workflow", "run", "--task", "Open work", "--out", str(log),
+        "--use-default-completion-conditions",
+    ) == 0
+    assert _run(
+        tmp_path, "skill", "evaluate", "--log", str(log), "--decision", "accepted",
+        "--classification", "continuation", "--next-handling", "continue_next_step",
+        "--purpose-fit", "still fits", "--verified", "none", "--uncertainty", "none",
+    ) == 1
+
+
+def test_comparability_gap_requires_a_reason(tmp_path: Path) -> None:
+    log = _closed_run(tmp_path)
+    assert _run(
+        tmp_path, "skill", "evaluate", "--log", str(log), "--decision", "accepted",
+        "--classification", "continuation", "--next-handling", "continue_next_step",
+        "--purpose-fit", "still fits", "--verified", "none", "--uncertainty", "none",
+        "--comparability", "gap",
+    ) == 1