xrefkit 0.3.0__tar.gz → 0.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.3.0
+Version: 0.4.1
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -91,7 +91,7 @@ XRefKit makes AI work explicit by separating:
 
 - Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
 - Knowledge: source-backed domain facts and local rules loaded only when needed
-- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Workflow protocol: the generic, deterministic control for Skill-backed and instruction-backed runs (phases, verification, closure)
 - Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
 - Evidence: logs, judgments, concerns, and quality checks
 - XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
@@ -109,6 +109,18 @@ and handoff records from collapsing into one opaque instruction block.
 4. Agents are routed semantically to the right Skill and load only the relevant context.
 5. Evidence and quality gates make incomplete or unsupported work visible.
 
+When an instruction has no matching Skill, open an instruction-backed workflow
+run explicitly. The run requires either user-supplied procedural completion
+conditions or an explicit opt-in to the repository defaults:
+
+```powershell
+xrefkit workflow run --task "Perform the requested procedure" `
+  --use-default-completion-conditions --json
+```
+
+`verify` and `close` determine procedural completion only. Output quality is
+recorded separately after human acceptance with the existing feedback record.
+
 ## Quick Start
 
 Install the package and initialize an instance:
@@ -133,6 +145,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.1}/README.md

@@ -52,7 +52,7 @@ XRefKit makes AI work explicit by separating:
 
 - Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
 - Knowledge: source-backed domain facts and local rules loaded only when needed
-- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Workflow protocol: the generic, deterministic control for Skill-backed and instruction-backed runs (phases, verification, closure)
 - Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
 - Evidence: logs, judgments, concerns, and quality checks
 - XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
@@ -70,6 +70,18 @@ and handoff records from collapsing into one opaque instruction block.
 4. Agents are routed semantically to the right Skill and load only the relevant context.
 5. Evidence and quality gates make incomplete or unsupported work visible.
 
+When an instruction has no matching Skill, open an instruction-backed workflow
+run explicitly. The run requires either user-supplied procedural completion
+conditions or an explicit opt-in to the repository defaults:
+
+```powershell
+xrefkit workflow run --task "Perform the requested procedure" `
+  --use-default-completion-conditions --json
+```
+
+`verify` and `close` determine procedural completion only. Output quality is
+recorded separately after human acceptance with the existing feedback record.
+
 ## Quick Start
 
 Install the package and initialize an instance:
@@ -94,6 +106,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.1}/pyproject.toml

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

xrefkit-0.4.1/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.1}/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.4.1/tests/test_instruction_workflow.py

@@ -0,0 +1,100 @@
+import contextlib
+import io
+import json
+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 test_instruction_workflow_requires_completion_conditions(tmp_path: Path) -> None:
+    out = tmp_path / "work" / "sessions" / "run.md"
+    assert _run(tmp_path, "workflow", "run", "--task", "Do work", "--out", str(out)) == 1
+    assert not out.exists()
+
+
+def test_instruction_workflow_uses_default_conditions_and_shared_protocol(tmp_path: Path) -> None:
+    out = tmp_path / "work" / "sessions" / "run.md"
+    assert _run(
+        tmp_path,
+        "workflow",
+        "run",
+        "--task",
+        "Do work",
+        "--out",
+        str(out),
+        "--use-default-completion-conditions",
+    ) == 0
+    text = out.read_text(encoding="utf-8")
+    assert "# Workflow Run Log" in text
+    assert "## Run Load Gate" in text
+    assert "- basis: `default`" in text
+    assert "- quality_policy: `human_acceptance`" in text
+
+    assert _run(
+        tmp_path,
+        "skill",
+        "workitem",
+        "--log",
+        str(out),
+        "--item",
+        "WI-001",
+        "--text",
+        "Perform the instruction",
+        "--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", "instruction:checker"),
+    ):
+        assert _run(
+            tmp_path,
+            "skill",
+            "artifact",
+            "--log",
+            str(out),
+            "--artifact",
+            artifact_id,
+            "--kind",
+            kind,
+            "--target",
+            target,
+            "--item",
+            "WI-001",
+            "--status",
+            "done",
+            "--role",
+            role,
+        ) == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(out), "--phase", "execution", "--status", "done", "--role", "instruction:executor") == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(out), "--phase", "handoff", "--status", "done", "--role", "instruction:handoff_owner") == 0
+    assert _run(tmp_path, "skill", "verify", "--log", str(out)) == 0
+
+    # Quality is a human decision and is recorded separately from progression.
+    assert _run(
+        tmp_path,
+        "skill",
+        "feedback",
+        "--log",
+        str(out),
+        "--kind",
+        "human",
+        "--status",
+        "accepted",
+        "--target",
+        "OUT-001",
+        "--note",
+        "human accepted output quality",
+    ) == 0
+    assert _run(tmp_path, "skill", "close", "--log", str(out)) == 0
+    assert "## Completion Conditions" in out.read_text(encoding="utf-8")

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

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