xrefkit 0.4.16__tar.gz → 0.5.0__tar.gz

{xrefkit-0.4.16/xrefkit.egg-info → xrefkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.16
+Version: 0.5.0
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -42,8 +42,8 @@ Dynamic: license-file
 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.
+It helps teams structure domain procedures and knowledge so that work can
+record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
@@ -61,24 +61,34 @@ 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
+- **Skills** — reusable procedures expressed as SkillDefinitions
+- **Knowledge** — source-backed domain facts and local rules resolved by XID
+  when a Skill run needs them
+- **Workflow protocol** — recorded progress, deterministic workflow-record
+  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
+- **Skill Run Dashboard** — inspect recorded Skill execution state, definition
+  identity, runtime binding, referenced XIDs, evidence, judgments, concerns,
+  and handoffs
 - **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.
 
+Current Skill authoring targets the one-document `skill_definition_v1` format.
+Existing `legacy_split_v1` Skills and unversioned historical run logs remain
+readable during migration. The [Workflow Runtime Binding](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F)
+defines how instruction-derived `capability`, `tuning`, `responsibility`, and
+`execution_mode` are captured; these are not fixed SkillDefinition properties.
+Knowledge used by a Skill remains separate and is resolved from the XID catalog
+when needed.
+
 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.
+helps people inspect recorded XID retrieval and use together with the run's
+evidence before a human accepts or hands off the result. The Dashboard reports
+recorded state and missing observations; it does not accept output quality.
 
 ## Quick start
 
@@ -104,12 +114,17 @@ python -m pip install "xrefkit[mcp]"
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+This command starts the optional catalog and runtime MCP adapter. This checkout
+does not implement management upload, staging, sealing, review, or adoption of
+uploaded SkillDefinition bytes into the active catalog.
+
 ## 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)
+- [Read the SkillDefinition v1 contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
 - [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)
 

{xrefkit-0.4.16 → xrefkit-0.5.0}/README.md

@@ -3,8 +3,8 @@
 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.
+It helps teams structure domain procedures and knowledge so that work can
+record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
@@ -22,24 +22,34 @@ 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
+- **Skills** — reusable procedures expressed as SkillDefinitions
+- **Knowledge** — source-backed domain facts and local rules resolved by XID
+  when a Skill run needs them
+- **Workflow protocol** — recorded progress, deterministic workflow-record
+  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
+- **Skill Run Dashboard** — inspect recorded Skill execution state, definition
+  identity, runtime binding, referenced XIDs, evidence, judgments, concerns,
+  and handoffs
 - **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.
 
+Current Skill authoring targets the one-document `skill_definition_v1` format.
+Existing `legacy_split_v1` Skills and unversioned historical run logs remain
+readable during migration. The [Workflow Runtime Binding](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F)
+defines how instruction-derived `capability`, `tuning`, `responsibility`, and
+`execution_mode` are captured; these are not fixed SkillDefinition properties.
+Knowledge used by a Skill remains separate and is resolved from the XID catalog
+when needed.
+
 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.
+helps people inspect recorded XID retrieval and use together with the run's
+evidence before a human accepts or hands off the result. The Dashboard reports
+recorded state and missing observations; it does not accept output quality.
 
 ## Quick start
 
@@ -65,12 +75,17 @@ python -m pip install "xrefkit[mcp]"
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+This command starts the optional catalog and runtime MCP adapter. This checkout
+does not implement management upload, staging, sealing, review, or adoption of
+uploaded SkillDefinition bytes into the active catalog.
+
 ## 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)
+- [Read the SkillDefinition v1 contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
 - [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)
 

{xrefkit-0.4.16 → xrefkit-0.5.0}/pyproject.toml

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

xrefkit-0.5.0/tests/test_artifact_selected_family.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+import pytest
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = [
+    ("xlsx_spec_traceability", "xlsx_spec_traceability", "A7C3E9D2F610", "2D1B6A9E7C40", "5A7C2D4E9130"),
+    ("marketing-explainer-video", "marketing_explainer_video", "B8F1A6C4D720", "5E147B19D33D", "A6B923E41178"),
+    ("marketing_slide_png", "marketing_slide_png", "C2E7B9F5A130", "91B67D4AC2F3", "5E2C4A90D711"),
+    ("import_skill", "import_skill", "D5A8C1E6B740", "7C2A492D2B72", "1DF4555E1B02"),
+]
+
+
+@pytest.mark.parametrize("directory,skill_id,xid,body_xid,meta_xid", CASES)
+def test_artifact_v1_parse_concrete_metadata_and_legacy(directory, skill_id, xid, body_xid, meta_xid):
+    repo = Path(__file__).resolve().parents[1]
+    relative = Path(f"skills/{directory}/SKILL.v1.md")
+    definition = load_skill_definition(repo / relative)
+    metadata = definition["metadata"]
+    assert metadata["skill_id"] == skill_id
+    assert metadata["xid"] == xid
+    assert set(metadata["aliases"]) == {body_xid, meta_xid}
+    assert metadata["inputs"] and metadata["outputs"]
+    assert metadata["control_refs"] == []
+    assert "CAP-" not in definition["method"]
+    assert "## Reporting Contract" not in definition["method"]
+    assert "skill_doc: `./SKILL.md`" in (repo / relative.parent / "meta.md").read_text()
+
+
+def test_artifact_v1_explicit_batch_selection_and_knowledge_resolution():
+    repo = Path(__file__).resolve().parents[1]
+    paths = [Path(f"skills/{directory}/SKILL.v1.md") for directory, *_ in CASES]
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    ids = {case[1] for case in CASES}
+    entries = {entry.skill_id: entry for entry in catalog.skills if entry.skill_id in ids}
+    assert set(entries) == ids
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries.values())
+    for directory, skill_id, *_ in CASES:
+        definition = load_skill_definition(repo / f"skills/{directory}/SKILL.v1.md")
+        need_ids = [need["id"] for need in definition["metadata"]["knowledge_needs"]]
+        result = catalog.resolve_skill_knowledge(skill_id, need_ids)
+        assert result["unresolved_activation"] == []
+        assert result["unsatisfied_required"] == []

{xrefkit-0.4.16 → xrefkit-0.5.0}/tests/test_boundary_analysis.py

@@ -17,8 +17,9 @@ class BoundaryAnalysisTests(unittest.TestCase):
         xids: list[str],
         *,
         feedback: list[dict[str, str]] | None = None,
+        **context: str,
     ) -> dict[str, object]:
-        return {
+        run: dict[str, object] = {
             "path": path,
             "name": Path(path).name,
             "skill_id": skill_id,
@@ -41,6 +42,8 @@ class BoundaryAnalysisTests(unittest.TestCase):
             "observation_events": feedback or [],
             "mcp_events": [],
         }
+        run.update(context)
+        return run
 
     def _payload(self) -> dict[str, object]:
         xid_a = "XID-A-001"
@@ -92,6 +95,44 @@ class BoundaryAnalysisTests(unittest.TestCase):
         self.assertEqual(4, xid_row["run_count"])
         self.assertEqual(4, xid_row["used_count"])
 
+    def test_analysis_does_not_combine_distinct_definition_bindings(self) -> None:
+        feedback = [{"event": "human.feedback", "status": "corrected", "target": "OUT-001"}]
+        runs = [
+            self._run(
+                "alpha", f"a-{index}.md", ["XID-A"], feedback=feedback if index == 1 else [],
+                definition_format="skill_definition_v1", definition_xid="DEF-A", definition_sha256="sha-a",
+                capability="analysis", tuning="bounded", responsibility="report", execution_mode="subagent_required",
+            )
+            for index in (1, 2)
+        ] + [
+            self._run(
+                "alpha", f"b-{index}.md", ["XID-B"], feedback=feedback if index == 1 else [],
+                definition_format="skill_definition_v1", definition_xid="DEF-A", definition_sha256="sha-b",
+                capability="analysis", tuning="deep", responsibility="report", execution_mode="subagent_required",
+            )
+            for index in (1, 2)
+        ]
+
+        report = analyze_dashboard_payload({"runs": runs}, min_samples=2)
+        categories = {item["category"] for item in report["proposals"]}
+
+        self.assertNotIn("split", categories)
+        self.assertNotIn("skill_correction", categories)
+
+    def test_merge_requires_samples_under_the_same_runtime_binding(self) -> None:
+        runs = [
+            self._run(
+                skill, f"{skill}-{index}.md", ["XID-A"],
+                capability="analysis", tuning=tuning, responsibility="report", execution_mode="subagent_required",
+            )
+            for skill, tuning in (("alpha", "bounded"), ("beta", "deep"))
+            for index in (1, 2)
+        ]
+
+        report = analyze_dashboard_payload({"runs": runs}, min_samples=2)
+
+        self.assertNotIn("merge", {item["category"] for item in report["proposals"]})
+
     def test_markdown_explains_proposal_only_boundary(self) -> None:
         markdown = render_markdown(analyze_dashboard_payload(self._payload(), source_hash="source-001"))
 

xrefkit-0.5.0/tests/test_brownfield_csharp_structure_definitions.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = {
+    "brownfield-workflow": ("brownfield_workflow", "E1A7C4D9B260", "A17C4E8B2D91", "9B3D7A1C4E20"),
+    "csharp_error_policy_extraction": ("csharp_error_policy_extraction", "F2B8D5A1C370", "FE342FB520D0", "B150A2A54169"),
+    "source_structure_overview": ("source_structure_overview", "A6E3C9F2B470", "423C8B8F8AD0", "907B100F9F9D"),
+}
+
+
+def test_tracked_trio_parse_aliases_metadata_and_legacy_readability():
+    repo = Path(__file__).resolve().parents[1]
+    for directory, (skill_id, xid, body_xid, meta_xid) in CASES.items():
+        path = repo / "skills" / directory / "SKILL.v1.md"
+        definition = load_skill_definition(path)
+        metadata = definition["metadata"]
+        assert metadata["skill_id"] == skill_id
+        assert metadata["xid"] == xid
+        assert set(metadata["aliases"]) == {body_xid, meta_xid}
+        assert metadata["control_refs"] == []
+        for forbidden in ("capability", "tuning", "responsibility", "execution_mode", "model", "maturity"):
+            assert forbidden not in metadata
+        for common in ("## Reporting Contract", "## Logging", "## Context Direction Guard"):
+            assert common not in definition["method"]
+        assert f"<!-- xid: {body_xid} -->" in (repo / "skills" / directory / "SKILL.md").read_text(encoding="utf-8")
+        assert f"<!-- xid: {meta_xid} -->" in (repo / "skills" / directory / "meta.md").read_text(encoding="utf-8")
+
+
+def test_tracked_trio_combined_catalog_and_knowledge_resolution():
+    repo = Path(__file__).resolve().parents[1]
+    paths = [repo / "skills" / directory / "SKILL.v1.md" for directory in CASES]
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    entries = {entry.skill_id: entry for entry in catalog.skills if entry.skill_id in {case[0] for case in CASES.values()}}
+    assert set(entries) == {case[0] for case in CASES.values()}
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries.values())
+    for directory, (skill_id, *_rest) in CASES.items():
+        definition = load_skill_definition(repo / "skills" / directory / "SKILL.v1.md")
+        need_ids = [need["id"] for need in definition["metadata"]["knowledge_needs"]]
+        result = catalog.resolve_skill_knowledge(skill_id, need_ids)
+        assert result["unresolved_activation"] == []
+        assert result["unsatisfied_required"] == []

xrefkit-0.5.0/tests/test_business_intake_conversation_definitions.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = [
+    ("conversation_topic_branch_mapping", "9D6A4F2B1C80", "2E755FFA0A86", "59777C84933D", []),
+    ("decision_topology_analysis", "B7E3C1A9D640", "502BB91D25FA", "2C927E868B25", ["7B3E5D1A6102", "7B3E5D1A6103"]),
+]
+
+
+def test_business_intake_v1_definitions_parse_aliases_and_preserve_legacy():
+    repo = Path(__file__).resolve().parents[1]
+    for skill_id, xid, body_xid, meta_xid, _ in CASES:
+        relative = Path("skills/packs/business-intake") / skill_id / "SKILL.v1.md"
+        definition = load_skill_definition(repo / relative)
+        metadata = definition["metadata"]
+        assert metadata["xid"] == xid
+        assert set(metadata["aliases"]) == {body_xid, meta_xid}
+        assert metadata["control_refs"] == []
+        for forbidden in ("capability", "tuning", "responsibility", "execution_mode", "model", "maturity"):
+            assert forbidden not in metadata
+        assert "## Context Direction Guard" not in definition["method"]
+        assert "## Reporting Contract" not in definition["method"]
+        assert f"<!-- xid: {body_xid} -->" in (repo / relative.parent / "SKILL.md").read_text(encoding="utf-8")
+        assert f"skill_doc: `./SKILL.md`" in (repo / relative.parent / "meta.md").read_text(encoding="utf-8")
+
+
+def test_business_intake_v1_explicit_catalog_selection_and_knowledge_resolution():
+    repo = Path(__file__).resolve().parents[1]
+    paths = [Path("skills/packs/business-intake") / skill_id / "SKILL.v1.md" for skill_id, *_ in CASES]
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    entries = [entry for entry in catalog.skills if entry.skill_id in {case[0] for case in CASES}]
+    assert len(entries) == 2
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries)
+    assert {entry.definition_xid for entry in entries} == {case[1] for case in CASES}
+    for skill_id, _, _, _, seed_xids in CASES:
+        definition = load_skill_definition(repo / (Path("skills/packs/business-intake") / skill_id / "SKILL.v1.md"))
+        need_ids = [need["id"] for need in definition["metadata"]["knowledge_needs"]]
+        if need_ids:
+            resolved = catalog.resolve_skill_knowledge(skill_id, need_ids)
+            assert resolved["unresolved_activation"] == []
+            assert resolved["unsatisfied_required"] == []
+            assert {candidate["xid"] for need in resolved["needs"] for candidate in need["candidates"]} >= set(seed_xids)
+

xrefkit-0.5.0/tests/test_business_intake_definition.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = (
+    ("business_learning_interview", "B6C4E9A2D781", "4D8E1A7C5B92", "2B6D4F18A3C1", "7B3E5D1A6103"),
+    ("business_intake_scoping", "B6C4E9A2D782", "6F2A9C41E8B3", "4E9B2C18D740", "7B3E5D1A6102"),
+)
+
+
+def test_business_intake_v1_definitions_parse_select_resolve_and_preserve_legacy():
+    repo = Path(__file__).resolve().parents[1]
+    paths = []
+    for skill_id, xid, body_xid, meta_xid, rule_xid in CASES:
+        directory = repo / "skills/packs/business-intake" / skill_id
+        definition_path = directory / "SKILL.v1.md"
+        paths.append(definition_path.relative_to(repo))
+        definition = load_skill_definition(definition_path)
+        metadata = definition["metadata"]
+        assert metadata["schema_version"] == 1
+        assert metadata["skill_id"] == skill_id
+        assert metadata["xid"] == xid
+        assert set(metadata["aliases"]) == {body_xid, meta_xid}
+        assert metadata["xid"] not in metadata["aliases"]
+        assert len(metadata["aliases"]) == len(set(metadata["aliases"]))
+        assert not {
+            "capability", "tuning", "responsibility", "execution_mode",
+            "model", "model_tier", "maturity",
+        } & set(metadata)
+        assert metadata["control_refs"] == []
+        assert metadata["knowledge_needs"][0]["seed_xids"] == [rule_xid]
+        assert "docs/packs/business-intake/" in definition["method"]
+
+        catalog = XRefCatalog.build(repo, skill_definition_paths=[definition_path.relative_to(repo)])
+        entries = [entry for entry in catalog.skills if entry.skill_id == skill_id]
+        assert len(entries) == 1
+        assert entries[0].definition_format == "skill_definition_v1"
+        assert entries[0].definition_xid == xid
+        resolved = catalog.resolve_skill_knowledge(skill_id, ["business_" + ("learning_interview" if skill_id == "business_learning_interview" else "intake_scoping") + "_rules"])
+        assert resolved["unresolved_activation"] == []
+        assert resolved["unsatisfied_required"] == []
+        assert resolved["needs"][0]["satisfied"] is True
+
+        legacy = (directory / "SKILL.md").read_text(encoding="utf-8")
+        meta = (directory / "meta.md").read_text(encoding="utf-8")
+        assert f"<!-- xid: {body_xid} -->" in legacy
+        assert f"<!-- xid: {meta_xid} -->" in meta
+        assert "skill_doc: `./SKILL.md`" in meta
+
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    assert {entry.skill_id for entry in catalog.skills if entry.definition_format == "skill_definition_v1"} == {
+        "business_learning_interview", "business_intake_scoping"
+    }

xrefkit-0.5.0/tests/test_catalog_preparation_definition.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+import pytest
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = [
+    ("domain_knowledge_catalog_preparation", "skills/os/domain_knowledge_catalog_preparation", "A7C9E2D4F610", "EE95165681E8", "A409BACC6918"),
+    ("skill_flow_authoring", "skills/os/skill_flow_authoring", "B8D1A4C7E260", "C1B7A42D8E53", "D37E2B5C8A41"),
+    ("test_tool_catalog_preparation", "skills/test_tool_catalog_preparation", "C9E2B5D8F370", "DE815228B04C", "F2A36B52C0EB"),
+]
+
+
+@pytest.mark.parametrize("skill_id,folder,xid,body_xid,meta_xid", CASES)
+def test_v1_definitions_parse_with_aliases_and_concrete_metadata(skill_id, folder, xid, body_xid, meta_xid):
+    repo = Path(__file__).resolve().parents[1]
+    definition_path = repo / folder / "SKILL.v1.md"
+    definition = load_skill_definition(definition_path)
+    metadata = definition["metadata"]
+    assert metadata["skill_id"] == skill_id
+    assert metadata["xid"] == xid
+    assert set(metadata["aliases"]) == {body_xid, meta_xid}
+    assert metadata["inputs"] and metadata["outputs"]
+    assert metadata["control_refs"] == []
+    assert not any(key in metadata for key in ("capability", "tuning", "responsibility", "execution_mode", "model", "model_tier", "maturity"))
+    assert "CAP-" not in definition["method"]
+    assert "## Reporting Contract" not in definition["method"]
+    assert "## Required Knowledge (XID)" not in definition["method"]
+    assert (repo / folder / "SKILL.md").read_text(encoding="utf-8").startswith("<!-- xid: ")
+    assert (repo / folder / "meta.md").read_text(encoding="utf-8").startswith("<!-- xid: ")
+
+
+def test_explicit_catalog_and_knowledge_resolution_cover_the_trio():
+    repo = Path(__file__).resolve().parents[1]
+    paths = [repo / folder / "SKILL.v1.md" for _, folder, *_ in CASES]
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    entries = {entry.skill_id: entry for entry in catalog.skills if entry.skill_id in {case[0] for case in CASES}}
+    assert set(entries) == {case[0] for case in CASES}
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries.values())
+    for skill_id, folder, *_ in CASES:
+        definition = load_skill_definition(repo / folder / "SKILL.v1.md")
+        need_ids = [need["id"] for need in definition["metadata"]["knowledge_needs"]]
+        result = catalog.resolve_skill_knowledge(skill_id, need_ids)
+        assert result["unresolved_activation"] == []
+        assert result["unsatisfied_required"] == []

{xrefkit-0.4.16 → xrefkit-0.5.0}/tests/test_cli.py

@@ -307,7 +307,15 @@ class CliTests(unittest.TestCase):
             text = out.read_text(encoding="utf-8")
             self.assertIn("## Skill Load Gate", text)
             self.assertIn("## Runtime Role Assignment", text)
-            self.assertIn("## Capability Layering", text)
+            self.assertIn("## Workflow Runtime Binding", text)
+            runtime_role_assignment = text.split("## Runtime Role Assignment", 1)[1].split("## Role Responsibilities", 1)[0]
+            self.assertNotIn("- capability: ", runtime_role_assignment)
+            self.assertNotIn("- tuning: ", runtime_role_assignment)
+            self.assertNotIn("- responsibility: ", runtime_role_assignment)
+            self.assertIn("- owner: `workflow_protocol`", text)
+            self.assertIn("- contract_xid: `8D50A972BA9F`", text)
+            self.assertIn("- source: `legacy_meta_compatibility`", text)
+            self.assertIn("- instruction_basis: `run.task`", text)
             self.assertIn("- capability_layering: `required`", text)
             self.assertIn("- workflow_protocol: `required`", text)
             self.assertIn("- tuning: `sample specialization`", text)

xrefkit-0.5.0/tests/test_code_constraint_definition.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+def test_code_constraint_v1_parses_with_unique_legacy_aliases_and_catalog_selection():
+    repo = Path(__file__).resolve().parents[1]
+    relative = Path("skills/packs/constraint-derivation/code_constraint_derivation/SKILL.v1.md")
+    definition = load_skill_definition(repo / relative)
+    metadata = definition["metadata"]
+
+    assert metadata["schema_version"] == 1
+    assert metadata["xid"] == "7C4E9A1B2D60"
+    assert set(metadata["aliases"]) == {"D4701BFC6EA4", "D4701BFC6EA5"}
+    assert metadata["xid"] not in metadata["aliases"]
+    assert len(metadata["aliases"]) == len(set(metadata["aliases"]))
+    assert not {"capability", "tuning", "responsibility", "execution_mode", "model_tier", "maturity"} & set(metadata)
+
+    catalog = XRefCatalog.build(repo, skill_definition_paths=[relative])
+    entries = [entry for entry in catalog.skills if entry.skill_id == "code_constraint_derivation"]
+    assert len(entries) == 1
+    assert entries[0].definition_format == "skill_definition_v1"
+    assert entries[0].definition_xid == metadata["xid"]
+
+
+def test_code_constraint_v1_resolves_selected_knowledge_and_legacy_files_are_unchanged():
+    repo = Path(__file__).resolve().parents[1]
+    relative = Path("skills/packs/constraint-derivation/code_constraint_derivation/SKILL.v1.md")
+    definition = load_skill_definition(repo / relative)
+    need_ids = [need["id"] for need in definition["metadata"]["knowledge_needs"]]
+
+    catalog = XRefCatalog.build(repo, skill_definition_paths=[relative])
+    result = catalog.resolve_skill_knowledge("code_constraint_derivation", need_ids)
+    assert result["unresolved_activation"] == []
+    assert result["unsatisfied_required"] == []
+    assert [need["id"] for need in result["needs"]] == need_ids
+    assert all(need["activation_state"] == "active" for need in result["needs"])
+    assert all(need["satisfied"] is True for need in result["needs"])
+
+    meta = (repo / "skills/packs/constraint-derivation/code_constraint_derivation/meta.md").read_text(encoding="utf-8")
+    legacy = (repo / "skills/packs/constraint-derivation/code_constraint_derivation/SKILL.md").read_text(encoding="utf-8")
+    assert "skill_doc: `./SKILL.md`" in meta
+    assert "<!-- xid: D4701BFC6EA4 -->" in meta
+    assert "<!-- xid: D4701BFC6EA5 -->" in legacy
+    assert "## Reporting Contract" not in definition["method"]
+    assert "111D282CA0EA" in definition["metadata"]["control_refs"]

xrefkit-0.5.0/tests/test_constraint_derivation_family_definition.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+
+import pytest
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = [
+    ("integration_constraint_derivation", "9A1C4E7D2B60", "E547F90B1235", "E547F90B1234", ["81A6C4E2B190", "6F0D7C1A2E44"]),
+    ("integration_scenario_derivation", "5F8B2D6A1C90", "F6923D1E80C9", "F6923D1E80C8", ["81A6C4E2B190", "C3F60AEB5D93"]),
+    ("logic_constraint_derivation", "3D7A9E2B4C60", "D436E8FA0124", "D436E8FA0123", ["81A6C4E2B190", "4E5B8923C912"]),
+    ("ui_constraint_derivation", "6B1F8D3A5E20", "C325D7E9F123", "C325D7E9F122", ["81A6C4E2B190", "31C5A06B7E22"]),
+    ("constraint_derivation_index", "A4C9E2B7D160", "A103B5C7D901", "A103B5C7D900", ["81A6C4E2B190"]),
+]
+
+
+@pytest.mark.parametrize("skill_id,xid,body_xid,meta_xid,seed_xids", CASES)
+def test_constraint_derivation_v1_migration(skill_id, xid, body_xid, meta_xid, seed_xids):
+    repo = Path(__file__).resolve().parents[1]
+    relative = Path("skills/packs/constraint-derivation") / skill_id / "SKILL.v1.md"
+    definition = load_skill_definition(repo / relative)
+    metadata = definition["metadata"]
+    assert metadata["xid"] == xid
+    assert set(metadata["aliases"]) == {body_xid, meta_xid}
+    assert metadata["control_refs"] == ["111D282CA0EA"]
+    assert "## Reporting Contract" not in definition["method"]
+    assert "## Required Knowledge (XID)" not in definition["method"]
+    assert "Context direction guard" not in definition["method"]
+
+    legacy = (repo / relative.parent / "SKILL.md").read_bytes()
+    assert f"<!-- xid: {body_xid} -->".encode() in legacy
+    assert f"skill_doc: `./SKILL.md`".encode() in (repo / relative.parent / "meta.md").read_bytes()
+
+
+def test_constraint_derivation_v1_explicit_selection_and_knowledge_resolution():
+    repo = Path(__file__).resolve().parents[1]
+    paths = [Path("skills/packs/constraint-derivation") / skill / "SKILL.v1.md" for skill, *_ in CASES]
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    entries = [entry for entry in catalog.skills if entry.skill_id in {case[0] for case in CASES}]
+    assert len(entries) == len(CASES)
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries)
+    assert {entry.definition_xid for entry in entries} == {case[1] for case in CASES}
+
+    for skill_id, _, _, _, seed_xids in CASES:
+        relative = Path("skills/packs/constraint-derivation") / skill_id / "SKILL.v1.md"
+        definition = load_skill_definition(repo / relative)
+        result = catalog.resolve_skill_knowledge(skill_id, [need["id"] for need in definition["metadata"]["knowledge_needs"]])
+        assert result["unresolved_activation"] == []
+        assert result["unsatisfied_required"] == []
+        for expected, need in zip(seed_xids, result["needs"], strict=True):
+            assert expected in [candidate["xid"] for candidate in need["candidates"]]
+
+
+def test_complete_constraint_derivation_family_selects_without_identity_collisions():
+    repo = Path(__file__).resolve().parents[1]
+    family_root = Path("skills/packs/constraint-derivation")
+    paths = sorted(family_root.glob("*/SKILL.v1.md"))
+    relative_paths = [path.relative_to(repo) if path.is_absolute() else path for path in paths]
+
+    assert len(relative_paths) == 11
+    catalog = XRefCatalog.build(repo, skill_definition_paths=relative_paths)
+    family_ids = {path.parent.name for path in relative_paths}
+    entries = [entry for entry in catalog.skills if entry.skill_id in family_ids]
+
+    assert {entry.skill_id for entry in entries} == family_ids
+    assert len({entry.definition_xid for entry in entries}) == 11
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries)