xrefkit 0.4.8__tar.gz → 0.4.10__tar.gz

xrefkit-0.4.10/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: xrefkit
+Version: 0.4.10
+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.10/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.8 → xrefkit-0.4.10}/pyproject.toml

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

{xrefkit-0.4.8 → xrefkit-0.4.10}/tests/test_cli.py

@@ -1464,6 +1464,63 @@ class CliTests(unittest.TestCase):
             self.assertIn("## Closure Gate\n\n- status: `done`", text)
             self.assertIn("`closure` -> `done` role=`closure_gate`: closure gate accepted completed run", text)
 
+    def test_skill_import_invalid_batch_input_returns_safe_json_error(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "repo"
+            source = Path(tmp) / "not-a-batch"
+            source.mkdir()
+
+            stdout = io.StringIO()
+            stderr = io.StringIO()
+            with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+                exit_code = main(
+                    [
+                        "skill",
+                        "import",
+                        str(source),
+                        "--root",
+                        str(root),
+                        "--batch",
+                        "--json",
+                    ]
+                )
+
+            payload = json.loads(stdout.getvalue())
+            self.assertEqual(2, exit_code)
+            self.assertFalse(payload["ok"])
+            self.assertEqual("invalid_input", payload["error"]["code"])
+            self.assertEqual("batch source root must contain a skills/ directory", payload["error"]["message"])
+            self.assertNotIn(str(root), stdout.getvalue())
+            self.assertNotIn(str(source), stdout.getvalue())
+            self.assertEqual("", stderr.getvalue())
+
+    def test_skill_import_missing_document_returns_safe_text_error(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp) / "repo"
+            source = Path(tmp) / "empty-skill"
+            source.mkdir()
+
+            stdout = io.StringIO()
+            stderr = io.StringIO()
+            with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+                exit_code = main(
+                    [
+                        "skill",
+                        "import",
+                        str(source),
+                        "--root",
+                        str(root),
+                        "--skill-id",
+                        "legacy_review",
+                    ]
+                )
+
+            self.assertEqual(2, exit_code)
+            self.assertEqual("", stdout.getvalue())
+            self.assertIn("could not find SKILL.md or README.md in the source Skill directory", stderr.getvalue())
+            self.assertNotIn(str(root), stderr.getvalue())
+            self.assertNotIn(str(source), stderr.getvalue())
+
 
 if __name__ == "__main__":
     unittest.main()

{xrefkit-0.4.8 → xrefkit-0.4.10}/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.10/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"]