xrefkit 0.3.0__tar.gz → 0.4.0__tar.gz

{xrefkit-0.3.0 → xrefkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -133,6 +133,52 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+## Skill Run Observation Dashboard
+
+The local dashboard lets a human inspect Skill run status, closure and quality
+gates, evidence, handoffs, XID usage, missing information, and proposal-only
+boundary analysis.
+
+Start it from the repository root:
+
+```powershell
+python -m xrefkit dashboard serve --root .
+```
+
+Open [http://127.0.0.1:8765/](http://127.0.0.1:8765/). To open the browser
+automatically, add `--open-browser`. Use `--port 8766` when the default port is
+already in use, or `--sessions-dir path\to\sessions` when logs are stored
+elsewhere.
+
+The main tabs are:
+
+- **Overview / Attention / Closure**: run status, blockers, phases, closure,
+  and quality-gate state.
+- **Evidence / Handoff**: outputs, checks, handoffs, unknowns, risks, and
+  judgments needed for review and continuity.
+- **XID Usage**: selected, resolved, loaded, used, available, and unused XIDs.
+- **Analysis**: deterministic candidates for Knowledge correction, Skill
+  correction, split, merge, or usage-gap investigation. Review the evidence,
+  counterevidence, unknowns, and verification plan before changing canonical
+  files. The dashboard never applies these proposals automatically.
+- **Missing Information**: absent correlation, MCP, Knowledge, or feedback
+  records.
+
+Export the dashboard data and create a human-reviewable boundary report:
+
+```powershell
+python -m xrefkit dashboard data --root . > work/reports/dashboard-observation.json
+python -m xrefkit analysis boundary report `
+  --input work/reports/dashboard-observation.json `
+  --out work/reports/boundary-observation.md
+```
+
+The running dashboard also exposes JSON at
+[http://127.0.0.1:8765/api/runs](http://127.0.0.1:8765/api/runs) and health at
+[http://127.0.0.1:8765/healthz](http://127.0.0.1:8765/healthz). Stop a foreground
+server with `Ctrl+C`. For the complete review loop and screen guide, see the
+[Skill Run Observation Dashboard Usage guide](docs/guides/086_skill_run_observation_dashboard_usage.md).
+
 XRefKit is designed to be driven by an AI agent. The agent first resolves the
 startup contract XID, selects a Skill or source target from a compact catalog,
 and expands only the selected body.

{xrefkit-0.3.0 → xrefkit-0.4.0}/README.md

@@ -94,6 +94,52 @@ searches and XID resolutions then share the same `run_id` as the client Skill
 Run. The client separately records actual model-context loading and judgment
 application with `xrefkit skill knowledge --action load|apply`.
 
+## Skill Run Observation Dashboard
+
+The local dashboard lets a human inspect Skill run status, closure and quality
+gates, evidence, handoffs, XID usage, missing information, and proposal-only
+boundary analysis.
+
+Start it from the repository root:
+
+```powershell
+python -m xrefkit dashboard serve --root .
+```
+
+Open [http://127.0.0.1:8765/](http://127.0.0.1:8765/). To open the browser
+automatically, add `--open-browser`. Use `--port 8766` when the default port is
+already in use, or `--sessions-dir path\to\sessions` when logs are stored
+elsewhere.
+
+The main tabs are:
+
+- **Overview / Attention / Closure**: run status, blockers, phases, closure,
+  and quality-gate state.
+- **Evidence / Handoff**: outputs, checks, handoffs, unknowns, risks, and
+  judgments needed for review and continuity.
+- **XID Usage**: selected, resolved, loaded, used, available, and unused XIDs.
+- **Analysis**: deterministic candidates for Knowledge correction, Skill
+  correction, split, merge, or usage-gap investigation. Review the evidence,
+  counterevidence, unknowns, and verification plan before changing canonical
+  files. The dashboard never applies these proposals automatically.
+- **Missing Information**: absent correlation, MCP, Knowledge, or feedback
+  records.
+
+Export the dashboard data and create a human-reviewable boundary report:
+
+```powershell
+python -m xrefkit dashboard data --root . > work/reports/dashboard-observation.json
+python -m xrefkit analysis boundary report `
+  --input work/reports/dashboard-observation.json `
+  --out work/reports/boundary-observation.md
+```
+
+The running dashboard also exposes JSON at
+[http://127.0.0.1:8765/api/runs](http://127.0.0.1:8765/api/runs) and health at
+[http://127.0.0.1:8765/healthz](http://127.0.0.1:8765/healthz). Stop a foreground
+server with `Ctrl+C`. For the complete review loop and screen guide, see the
+[Skill Run Observation Dashboard Usage guide](docs/guides/086_skill_run_observation_dashboard_usage.md).
+
 XRefKit is designed to be driven by an AI agent. The agent first resolves the
 startup contract XID, selects a Skill or source target from a compact catalog,
 and expands only the selected body.

{xrefkit-0.3.0 → xrefkit-0.4.0}/pyproject.toml

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

xrefkit-0.4.0/tests/test_boundary_analysis.py

@@ -0,0 +1,157 @@
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from xrefkit.__main__ import main
+from xrefkit.boundary_analysis import analyze_dashboard_payload, render_markdown
+
+
+class BoundaryAnalysisTests(unittest.TestCase):
+    def _run(
+        self,
+        skill_id: str,
+        path: str,
+        xids: list[str],
+        *,
+        feedback: list[dict[str, str]] | None = None,
+    ) -> dict[str, object]:
+        return {
+            "path": path,
+            "name": Path(path).name,
+            "skill_id": skill_id,
+            "run_id": f"run-{path}",
+            "mcp_session_id": f"mcp-{path}",
+            "repository_fingerprint": "repo-001",
+            "status": "closed",
+            "closure_status": "done",
+            "quality_required": True,
+            "quality_status": "done",
+            "selected_xids": xids,
+            "queried_xids": xids,
+            "loaded_xids": xids,
+            "used_xids": xids,
+            "unused_xids": [],
+            "available_xids": xids,
+            "queried_not_loaded_xids": [],
+            "loaded_not_applied_xids": [],
+            "missing_information": [],
+            "observation_events": feedback or [],
+            "mcp_events": [],
+        }
+
+    def _payload(self) -> dict[str, object]:
+        xid_a = "XID-A-001"
+        xid_b = "XID-B-001"
+        return {
+            "schema": "xrefkit.dashboard/v1",
+            "audit_errors": [],
+            "runs": [
+                self._run(
+                    "alpha",
+                    "work/sessions/alpha-a-1.md",
+                    [xid_a],
+                    feedback=[
+                        {"event": "human.feedback", "status": "corrected", "target": xid_a, "note": "wrong fact"},
+                        {"event": "human.feedback", "status": "corrected", "target": "OUT-001", "note": "wrong procedure"},
+                    ],
+                ),
+                self._run(
+                    "alpha",
+                    "work/sessions/alpha-a-2.md",
+                    [xid_a],
+                    feedback=[
+                        {"event": "human.feedback", "status": "rejected", "target": xid_a, "note": "stale fact"},
+                        {"event": "human.feedback", "status": "rejected", "target": "OUT-002", "note": "wrong decision"},
+                    ],
+                ),
+                self._run("alpha", "work/sessions/alpha-b-1.md", [xid_b]),
+                self._run("alpha", "work/sessions/alpha-b-2.md", [xid_b]),
+                self._run("beta", "work/sessions/beta-1.md", [xid_a, xid_b]),
+                self._run("beta", "work/sessions/beta-2.md", [xid_a, xid_b]),
+            ],
+        }
+
+    def test_analysis_emits_conservative_boundary_candidates(self) -> None:
+        report = analyze_dashboard_payload(self._payload(), source_hash="source-001", min_samples=2)
+
+        self.assertEqual("xrefkit.boundary_observation/v1", report["schema"])
+        self.assertEqual("proposal_only", report["status"])
+        self.assertEqual(6, report["sample_count"])
+        self.assertEqual(6, report["correlation"]["exact"])
+        categories = {item["category"] for item in report["proposals"]}
+        self.assertIn("split", categories)
+        self.assertIn("merge", categories)
+        self.assertIn("knowledge_correction", categories)
+        self.assertIn("skill_correction", categories)
+        self.assertTrue(all(item["decision"]["status"] == "pending" for item in report["proposals"]))
+
+        xid_row = next(item for item in report["xid_usage"] if item["xid"] == "XID-A-001")
+        self.assertEqual(4, xid_row["run_count"])
+        self.assertEqual(4, xid_row["used_count"])
+
+    def test_markdown_explains_proposal_only_boundary(self) -> None:
+        markdown = render_markdown(analyze_dashboard_payload(self._payload(), source_hash="source-001"))
+
+        self.assertIn("Proposal-only output", markdown)
+        self.assertIn("## Proposals", markdown)
+        self.assertIn("Counterevidence", markdown)
+        self.assertIn("## Decision", markdown)
+        self.assertIn("XID-A-001", markdown)
+
+    def test_cli_writes_markdown_and_can_emit_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            source = root / "dashboard.json"
+            output = root / "reports" / "boundary.md"
+            source.write_text(json.dumps(self._payload()), encoding="utf-8")
+            stdout = io.StringIO()
+            with contextlib.redirect_stdout(stdout):
+                result = main(
+                    [
+                        "analysis",
+                        "boundary",
+                        "report",
+                        "--input",
+                        str(source),
+                        "--out",
+                        str(output),
+                        "--json",
+                    ]
+                )
+
+            self.assertEqual(0, result)
+            self.assertTrue(output.exists())
+            self.assertIn("Proposal-only output", output.read_text(encoding="utf-8"))
+            response = json.loads(stdout.getvalue())
+            self.assertEqual("proposal_only", response["status"])
+            self.assertEqual(4, response["summary"]["proposals"])
+
+    def test_invalid_dashboard_input_fails_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            source = Path(tmp) / "invalid.json"
+            output = Path(tmp) / "boundary.md"
+            source.write_text(json.dumps({"runs": "not-a-list"}), encoding="utf-8")
+            stdout = io.StringIO()
+            with contextlib.redirect_stdout(stdout):
+                result = main(
+                    [
+                        "analysis",
+                        "boundary",
+                        "report",
+                        "--input",
+                        str(source),
+                        "--out",
+                        str(output),
+                    ]
+                )
+
+            self.assertEqual(1, result)
+            self.assertFalse(output.exists())
+            self.assertIn("runs array", stdout.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

{xrefkit-0.3.0 → xrefkit-0.4.0}/tests/test_dashboard.py

@@ -379,6 +379,20 @@ class DashboardTests(unittest.TestCase):
             self.assertEqual({}, by_run)
             self.assertIn("cannot read audit log", errors[0])
 
+    def test_dashboard_payload_includes_proposal_only_boundary_analysis(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._write_closed_run(root)
+
+            payload = build_payload(root, root / "work" / "sessions")
+            analysis = payload["boundary_analysis"]
+
+            self.assertIsInstance(analysis, dict)
+            self.assertEqual("xrefkit.boundary_observation/v1", analysis["schema"])
+            self.assertEqual("proposal_only", analysis["status"])
+            self.assertEqual(1, analysis["sample_count"])
+            self.assertEqual(0, analysis["summary"]["proposals"])
+
     def test_dashboard_html_splits_categories(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:
             root = Path(tmp)
@@ -392,6 +406,7 @@ class DashboardTests(unittest.TestCase):
             self.assertIn('data-panel="evidence"', html)
             self.assertIn('data-panel="handoff"', html)
             self.assertIn('data-panel="xids"', html)
+            self.assertIn('data-panel="analysis"', html)
             self.assertIn('data-panel="missing-information"', html)
             self.assertIn('id="overview"', html)
             self.assertIn('id="attention"', html)
@@ -399,8 +414,62 @@ class DashboardTests(unittest.TestCase):
             self.assertIn('id="evidence"', html)
             self.assertIn('id="handoff"', html)
             self.assertIn('id="xids"', html)
+            self.assertIn('id="analysis"', html)
             self.assertIn('id="missing-information"', html)
+            self.assertIn("Proposal-only analysis", html)
+            self.assertIn("No boundary proposals reached", html)
             self.assertIn("Missing Information Ranking", html)
             self.assertIn("Available Knowledge XIDs (base/local)", html)
             self.assertIn("local-service-map-001", html)
             self.assertIn("LOCAL-KNOWLEDGE-UNUSED-001", html)
+            self.assertIn('id="run-search"', html)
+            self.assertIn('data-status="blocked"', html)
+            self.assertIn('id="refresh-runs"', html)
+            self.assertIn("async function refreshDashboard()", html)
+            self.assertIn("selectRun(run.dataset.runPath)", html)
+            self.assertIn("data-run-path=", html)
+
+    def test_dashboard_html_search_index_contains_run_correlation_fields(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._write_closed_run(root)
+
+            payload = build_payload(root, root / "work" / "sessions")
+            run_id = payload["runs"][0]["run_id"]
+            html = _html_page(payload)
+
+            self.assertIsNotNone(run_id)
+            self.assertIn(str(run_id).lower(), html)
+            self.assertIn("sample_skill", html)
+
+    def test_dashboard_html_escapes_boundary_proposal_fields(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._write_closed_run(root)
+
+            payload = build_payload(root, root / "work" / "sessions")
+            payload["boundary_analysis"]["summary"]["proposals"] = 1
+            payload["boundary_analysis"]["proposals"] = [
+                {
+                    "proposal_id": "bo-test",
+                    "proposal": "investigate",
+                    "category": "skill_correction",
+                    "skill_ids": ["sample_skill"],
+                    "subject_xids": ["xid-test"],
+                    "support": 2,
+                    "evidence_refs": ["<script>alert(1)</script>"],
+                    "rationale": "<script>alert(2)</script>",
+                    "counterevidence": ["counter"],
+                    "unknowns": ["unknown"],
+                    "verification_plan": ["verify"],
+                    "decision": {"status": "pending", "owner": None},
+                }
+            ]
+
+            html = _html_page(payload)
+
+            self.assertIn("bo-test", html)
+            self.assertIn("Counterevidence", html)
+            self.assertIn("&lt;script&gt;alert(1)&lt;/script&gt;", html)
+            self.assertIn("&lt;script&gt;alert(2)&lt;/script&gt;", html)
+            self.assertNotIn("<script>alert(1)", html)

{xrefkit-0.3.0 → xrefkit-0.4.0}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"