xrefkit 0.4.2__tar.gz → 0.4.4__tar.gz

{xrefkit-0.4.2 → xrefkit-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.2
+Version: 0.4.4
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -126,7 +126,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -140,6 +169,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned

{xrefkit-0.4.2 → xrefkit-0.4.4}/README.md

@@ -87,7 +87,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -101,6 +130,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned

{xrefkit-0.4.2 → xrefkit-0.4.4}/pyproject.toml

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

{xrefkit-0.4.2 → xrefkit-0.4.4}/tests/test_instruction_workflow.py

@@ -150,3 +150,23 @@ def test_workitem_requires_criterion_or_explicit_unknown_reason(tmp_path: Path)
     assert "criterion=`` reason=`The business owner has not defined the acceptance outcome`" in text
     assert _run(tmp_path, "skill", "phase", "--log", str(out), "--phase", "execution", "--status", "done", "--role", "instruction:executor") == 0
     assert _run(tmp_path, "skill", "verify", "--log", str(out)) == 1
+
+
+def test_workitem_criterion_is_immutable_and_changes_use_supersedes(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
+    base = [
+        "skill", "workitem", "--log", str(out), "--item", "WI-001",
+        "--text", "Implement original outcome", "--completion-criterion", "original outcome is verified",
+        "--status", "pending", "--role", "instruction:executor",
+    ]
+    assert _run(tmp_path, *base) == 0
+    assert _run(tmp_path, *base[:-6], "--completion-criterion", "different outcome is verified", "--status", "pending", "--role", "instruction:executor") == 1
+    assert _run(
+        tmp_path,
+        "skill", "workitem", "--log", str(out), "--item", "WI-002", "--supersedes", "WI-001",
+        "--text", "Implement revised outcome", "--completion-criterion", "revised outcome is verified",
+        "--status", "pending", "--role", "instruction:executor",
+    ) == 0
+    text = out.read_text(encoding="utf-8")
+    assert "WI-002" in text and "supersedes=`WI-001`" in text

xrefkit-0.4.4/tests/test_mcp_setup.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from xrefkit.__main__ import main
+
+
+def test_mcp_setup_writes_reviewable_workspace(tmp_path: Path, capsys) -> None:
+    output = tmp_path / "setup-output"
+    root = tmp_path / "repo"
+
+    assert main(["mcp", "setup", "--repo", str(root), "--output", str(output), "--json"]) == 0
+
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["output"] == str(output.resolve())
+    assert (output / "SETUP.md").is_file()
+    assert (output / "vscode-mcp.json").is_file()
+    assert (output / "AGENTS.md.append.md").is_file()
+    assert (output / "CLAUDE.md.append.md").is_file()
+    assert (output / "import-report.json").is_file()
+
+    vscode = json.loads((output / "vscode-mcp.json").read_text(encoding="utf-8"))
+    server = vscode["servers"]["xrefkit"]
+    assert server["type"] == "stdio"
+    assert server["args"][-2:] == ["--transport", "stdio"]
+
+
+def test_mcp_setup_imports_existing_batch_skill_before_writing_report(tmp_path: Path, capsys) -> None:
+    source = tmp_path / "existing"
+    skill = source / "skills" / "legacy-review"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("# Legacy Review\n\nReview the supplied change.\n", encoding="utf-8")
+    root = tmp_path / "repo"
+    output = tmp_path / "setup-output"
+
+    exit_code = main(
+        [
+            "mcp",
+            "setup",
+            "--repo",
+            str(root),
+            "--import",
+            str(source),
+            "--output",
+            str(output),
+            "--json",
+        ]
+    )
+    payload = json.loads(capsys.readouterr().out)
+    assert exit_code in {0, 1}
+    assert (root / "skills" / "imported.legacy-review" / "SKILL.md").is_file()
+    report = json.loads((output / "import-report.json").read_text(encoding="utf-8"))
+    assert report["import"]["converted_skills"][0]["skill_id"] == "imported.legacy-review"
+    assert payload["output"] == str(output.resolve())
+
+
+def test_mcp_setup_apply_copies_config_and_appends_instructions(tmp_path: Path, capsys) -> None:
+    output = tmp_path / "setup-output"
+    root = tmp_path / "repo"
+    root.mkdir()
+    assert main(["mcp", "setup", "--repo", str(root), "--output", str(output)]) == 0
+    capsys.readouterr()
+
+    assert main(["mcp", "setup-apply", "--source", str(output), "--repo", str(root)]) == 0
+    capsys.readouterr()
+    assert (root / ".vscode" / "mcp.json").is_file()
+    agents = (root / "AGENTS.md").read_text(encoding="utf-8")
+    assert "XRefKit MCP Skill Routing" in agents
+
+    assert main(["mcp", "setup-apply", "--source", str(output), "--repo", str(root)]) == 0
+    assert (root / "AGENTS.md").read_text(encoding="utf-8").count("XRefKit MCP Skill Routing") == 1

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.2"
+__version__ = "0.4.4"

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit/mcp/__init__.py

@@ -11,6 +11,16 @@ def main(argv: list[str] | None = None) -> int:
     from .server import main as server_main
 
     args = list(argv or [])
+    if args and args[0] == "setup":
+        from .setup import main as setup_main
+
+        if len(args) > 1 and args[1] == "apply":
+            return setup_main(["setup-apply", *args[2:]])
+        return setup_main(args)
+    if args and args[0] == "setup-apply":
+        from .setup import main as setup_main
+
+        return setup_main(args)
     if args and args[0] == "serve":
         args = args[1:]
     return server_main(args)

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit/mcp/bootstrap.py

@@ -37,6 +37,7 @@ import sys
 import urllib.request
 import zipfile
 from pathlib import Path
+from urllib.parse import urlsplit
 
 
 DIST_STATE_RELATIVE_PATH = ".xrefkit/dist-state.json"
@@ -50,6 +51,12 @@ class BootstrapError(RuntimeError):
     pass
 
 
+def _validate_http_url(url: str) -> None:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise BootstrapError("bootstrap endpoints must use an absolute http(s) URL")
+
+
 def _ssl_context(ca_file: str | None) -> ssl.SSLContext:
     if ca_file:
         return ssl.create_default_context(cafile=ca_file)
@@ -57,8 +64,10 @@ def _ssl_context(ca_file: str | None) -> ssl.SSLContext:
 
 
 def http_get(url: str, ca_file: str | None = None, headers: dict[str, str] | None = None) -> bytes:
+    _validate_http_url(url)
     request = urllib.request.Request(url, headers=headers or {})
-    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:
+    # The URL scheme is validated above; B310 cannot infer that from Request.
+    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:  # nosec B310
         return response.read()
 
 
@@ -68,6 +77,7 @@ def http_post_json(
     ca_file: str | None = None,
     headers: dict[str, str] | None = None,
 ) -> tuple[bytes, dict[str, str]]:
+    _validate_http_url(url)
     request_headers = {
         "Content-Type": "application/json",
         "Accept": "application/json, text/event-stream",
@@ -79,7 +89,8 @@ def http_post_json(
         headers=request_headers,
         method="POST",
     )
-    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:
+    # The URL scheme is validated above; B310 cannot infer that from Request.
+    with urllib.request.urlopen(request, context=_ssl_context(ca_file)) as response:  # nosec B310
         return response.read(), {key.lower(): value for key, value in response.headers.items()}
 
 

xrefkit-0.4.4/xrefkit/mcp/setup.py

@@ -0,0 +1,234 @@
+"""Prepare an XRefKit repository and client configuration for MCP use."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+AGENT_APPEND = """## XRefKit MCP Skill Routing
+
+When the XRefKit MCP server is configured and available in this client, use
+its Skill catalog and semantic routing for Skill selection.
+
+The VS Code workspace MCP configuration is `.vscode/mcp.json`.
+
+Do not manually import or select individual Skill files during normal task
+execution. The administrator manages Skill registration; the client uses the
+MCP catalog to select and execute Skills.
+"""
+
+
+def _vscode_config(root: Path) -> dict[str, object]:
+    python_command = "python"
+    venv_python = root / ".venv" / "Scripts" / "python.exe"
+    if venv_python.is_file():
+        python_command = "${workspaceFolder}\\.venv\\Scripts\\python.exe"
+    return {
+        "servers": {
+            "xrefkit": {
+                "type": "stdio",
+                "command": python_command,
+                "args": [
+                    "-m",
+                    "xrefkit",
+                    "mcp",
+                    "serve",
+                    "--repo",
+                    "${workspaceFolder}",
+                    "--transport",
+                    "stdio",
+                ],
+            }
+        }
+    }
+
+
+def _run_xref_fix(root: Path) -> dict[str, object]:
+    proc = subprocess.run(
+        [sys.executable, "-m", "xrefkit", "xref", "fix", "--root", str(root), "--json"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    try:
+        payload: object = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        payload = {"stdout": proc.stdout.strip(), "stderr": proc.stderr.strip()}
+    return {"returncode": proc.returncode, "result": payload}
+
+
+def _run_skill_checks(root: Path, metas: list[Path]) -> list[dict[str, object]]:
+    results: list[dict[str, object]] = []
+    for meta in metas:
+        proc = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "xrefkit",
+                "skill",
+                "check",
+                "--root",
+                str(root),
+                "--meta",
+                str(meta),
+                "--level",
+                "trial",
+                "--json",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        try:
+            result: object = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            result = {"stdout": proc.stdout.strip(), "stderr": proc.stderr.strip()}
+        results.append({"meta": meta.relative_to(root).as_posix(), "returncode": proc.returncode, "result": result})
+    return results
+
+
+def _write_setup_files(
+    output: Path,
+    *,
+    root: Path,
+    import_report: dict[str, object] | None,
+    xref_report: dict[str, object],
+    checks: list[dict[str, object]],
+) -> None:
+    output.mkdir(parents=True, exist_ok=True)
+    (output / "vscode-mcp.json").write_text(
+        json.dumps(_vscode_config(root), ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    (output / "AGENTS.md.append.md").write_text(AGENT_APPEND, encoding="utf-8")
+    (output / "CLAUDE.md.append.md").write_text(AGENT_APPEND, encoding="utf-8")
+    report = {"root": str(root), "import": import_report, "xref_fix": xref_report, "skill_checks": checks}
+    (output / "import-report.json").write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    guide = f"""# XRefKit MCP setup review
+
+Generated setup files:
+
+- `vscode-mcp.json`: copy to `{(root / '.vscode' / 'mcp.json').as_posix()}`.
+- `AGENTS.md.append.md`: review and append to `AGENTS.md`.
+- `CLAUDE.md.append.md`: review and append to `CLAUDE.md`.
+- `import-report.json`: import, XID fix, and Skill validation results.
+
+The setup command does not modify client instruction files or overwrite an
+existing VS Code MCP configuration. Apply these files only after review.
+
+After applying the files, open the repository in VS Code and start the
+`xrefkit` MCP server from the MCP controls.
+"""
+    (output / "SETUP.md").write_text(guide, encoding="utf-8")
+
+
+def setup(args: argparse.Namespace) -> int:
+    root = Path(args.repo).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    output = Path(args.output).resolve() if args.output else Path(tempfile.mkdtemp(prefix="xrefkit-setup-"))
+    import_report: dict[str, object] | None = None
+    metas: list[Path] = []
+
+    if args.import_source:
+        from xrefkit.import_skill import convert_skill, convert_skill_tree
+
+        source = Path(args.import_source).resolve()
+        if (source / "skills").is_dir() or args.batch:
+            result = convert_skill_tree(
+                source_root=source,
+                repo_root=root,
+                skill_id_prefix=args.skill_id_prefix,
+                target_skill_root=root / "skills",
+                dry_run=False,
+            )
+            import_report = result.to_dict()
+        else:
+            if not args.skill_id:
+                raise SystemExit("--skill-id is required when --import is a single Skill directory")
+            result = convert_skill(
+                source_dir=source,
+                source_root=source.parent,
+                repo_root=root,
+                skill_id=args.skill_id,
+                target_skill_dir=root / "skills" / args.skill_id,
+                dry_run=False,
+            )
+            import_report = result.to_dict()
+
+        if isinstance(import_report, dict):
+            metas = [root / Path(item["meta_doc"]) for item in import_report.get("converted_skills", []) if item.get("meta_doc")]
+            if not metas and import_report.get("meta_doc"):
+                metas = [root / Path(import_report["meta_doc"])]
+
+    xref_report = _run_xref_fix(root)
+    checks = _run_skill_checks(root, metas)
+    _write_setup_files(output, root=root, import_report=import_report, xref_report=xref_report, checks=checks)
+
+    payload = {"ok": xref_report["returncode"] == 0 and all(item["returncode"] == 0 for item in checks), "output": str(output), "report": str(output / "import-report.json")}
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"setup workspace: {output}")
+        print(f"guide: {output / 'SETUP.md'}")
+        print(f"report: {output / 'import-report.json'}")
+    return 0 if payload["ok"] else 1
+
+
+def apply_setup(args: argparse.Namespace) -> int:
+    source = Path(args.source).resolve()
+    root = Path(args.repo).resolve()
+    if not source.is_dir():
+        raise SystemExit(f"setup workspace does not exist: {source}")
+    destinations = {
+        source / "vscode-mcp.json": root / ".vscode" / "mcp.json",
+        source / "AGENTS.md.append.md": root / "AGENTS.md",
+        source / "CLAUDE.md.append.md": root / "CLAUDE.md",
+    }
+    for candidate, destination in destinations.items():
+        if not candidate.is_file():
+            raise SystemExit(f"missing setup artifact: {candidate}")
+        if destination.name == "mcp.json":
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            if destination.exists() and destination.read_bytes() != candidate.read_bytes() and not args.force:
+                raise SystemExit(f"refusing to overwrite {destination}; use --force after review")
+            if not destination.exists() or destination.read_bytes() != candidate.read_bytes():
+                shutil.copyfile(candidate, destination)
+        else:
+            existing = destination.read_text(encoding="utf-8") if destination.exists() else ""
+            addition = candidate.read_text(encoding="utf-8")
+            if addition.strip() not in existing:
+                destination.write_text(existing.rstrip() + "\n\n" + addition, encoding="utf-8")
+    print(f"applied setup artifacts from: {source}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="xrefkit mcp")
+    sub = parser.add_subparsers(dest="command", required=True)
+    setup_parser = sub.add_parser("setup", help="import Skills and generate reviewable MCP setup artifacts")
+    setup_parser.add_argument("--repo", required=True)
+    setup_parser.add_argument("--import", dest="import_source", default=None, help="Skill directory or batch root")
+    setup_parser.add_argument("--batch", action="store_true")
+    setup_parser.add_argument("--skill-id-prefix", default="imported")
+    setup_parser.add_argument("--skill-id", default=None)
+    setup_parser.add_argument("--output", default=None, help="Setup workspace; defaults to a temporary folder")
+    setup_parser.add_argument("--json", action="store_true")
+    setup_parser.set_defaults(handler=setup)
+
+    apply_parser = sub.add_parser("setup-apply", help="apply reviewed setup artifacts")
+    apply_parser.add_argument("--source", required=True)
+    apply_parser.add_argument("--repo", required=True)
+    apply_parser.add_argument("--force", action="store_true")
+    apply_parser.set_defaults(handler=apply_setup)
+
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit/operations_cli.py

@@ -499,6 +499,7 @@ def _build_parser() -> argparse.ArgumentParser:
     p_skill_workitem.add_argument("--text", default=None, help="Work item text; required when adding a new item")
     p_skill_workitem.add_argument("--completion-criterion", default=None, help="Observable procedural condition for this work item")
     p_skill_workitem.add_argument("--criterion-unknown-reason", default=None, help="Why the completion criterion cannot yet be defined for unknown/blocked/escalated work")
+    p_skill_workitem.add_argument("--supersedes", default=None, help="Existing work item whose criterion is being replaced by this new item")
     p_skill_workitem.add_argument(
         "--status",
         required=True,

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit/skillrun.py

@@ -179,6 +179,12 @@ WORKLIST_ROWS = [
     ("Handoff", "Record outputs, unresolved items, next owner, and human decision points."),
 ]
 WORKITEM_RE = re.compile(
+    r"^- \[(?P<checkbox>[ x!])\] (?P<item_id>[A-Za-z0-9_.-]+) "
+    r"status=`(?P<status>[^`]+)` role=`(?P<role>[^`]+)` "
+    r"criterion=`(?P<criterion>[^`]*)` reason=`(?P<reason>[^`]*)` "
+    r"supersedes=`(?P<supersedes>[^`]*)`: (?P<text>.*)$"
+)
+WORKITEM_V2_RE = re.compile(
     r"^- \[(?P<checkbox>[ x!])\] (?P<item_id>[A-Za-z0-9_.-]+) "
     r"status=`(?P<status>[^`]+)` role=`(?P<role>[^`]+)` "
     r"criterion=`(?P<criterion>[^`]*)` reason=`(?P<reason>[^`]*)`: (?P<text>.*)$"
@@ -838,6 +844,21 @@ def _parse_work_items(text: str) -> list[dict[str, str]]:
                     "role": match.group("role"),
                     "criterion": match.group("criterion"),
                     "reason": match.group("reason"),
+                    "supersedes": match.group("supersedes"),
+                    "text": match.group("text"),
+                }
+            )
+            continue
+        match = WORKITEM_V2_RE.match(line)
+        if match:
+            items.append(
+                {
+                    "item_id": match.group("item_id"),
+                    "status": match.group("status"),
+                    "role": match.group("role"),
+                    "criterion": match.group("criterion"),
+                    "reason": match.group("reason"),
+                    "supersedes": "",
                     "text": match.group("text"),
                 }
             )
@@ -852,16 +873,17 @@ def _parse_work_items(text: str) -> list[dict[str, str]]:
                 "role": match.group("role"),
                 "criterion": "",
                 "reason": "legacy work item has no recorded completion criterion",
+                "supersedes": "",
                 "text": match.group("text"),
             }
         )
     return items
 
 
-def _render_workitem_line(*, item_id: str, status: str, role: str, criterion: str, reason: str, text: str) -> str:
+def _render_workitem_line(*, item_id: str, status: str, role: str, criterion: str, reason: str, supersedes: str, text: str) -> str:
     return (
         f"- [{_workitem_checkbox(status)}] {item_id} status=`{status}` role=`{role}` "
-        f"criterion=`{criterion}` reason=`{reason}`: {text}"
+        f"criterion=`{criterion}` reason=`{reason}` supersedes=`{supersedes}`: {text}"
     )
 
 
@@ -913,6 +935,7 @@ def update_work_item(args) -> SkillRunResult:
     item_text = str(args.text or "").strip()
     criterion = str(getattr(args, "completion_criterion", None) or "").strip().replace("`", "'").replace("\n", " ")
     reason = str(getattr(args, "criterion_unknown_reason", None) or "").strip().replace("`", "'").replace("\n", " ")
+    supersedes = str(getattr(args, "supersedes", None) or "").strip().replace("`", "'").replace("\n", " ")
     if not item_id:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["missing --item"])
     if status not in VALID_WORKITEM_STATUSES:
@@ -931,10 +954,21 @@ def update_work_item(args) -> SkillRunResult:
     items = _parse_work_items(text)
     existing = next((item for item in items if item["item_id"] == item_id), None)
     if existing:
+        existing_criterion = existing.get("criterion", "")
+        if criterion and criterion != existing_criterion:
+            return SkillRunResult(
+                ok=False,
+                skill_id=None,
+                skill_doc=None,
+                run_log=str(log_path),
+                errors=[
+                    f"completion criterion for {item_id} is immutable; create a new work item with --supersedes {item_id}"
+                ],
+            )
+        if supersedes:
+            return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=[f"--supersedes is only valid when creating a new work item, not updating {item_id}"])
         existing["status"] = status
         existing["role"] = role
-        if criterion:
-            existing["criterion"] = criterion
         if reason:
             existing["reason"] = reason
         if item_text:
@@ -942,7 +976,9 @@ def update_work_item(args) -> SkillRunResult:
     else:
         if not item_text:
             return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["new work item requires --text"])
-        items.append({"item_id": item_id, "status": status, "role": role, "criterion": criterion, "reason": reason, "text": item_text})
+        if supersedes and not any(item["item_id"] == supersedes for item in items):
+            return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=[f"superseded work item not found: {supersedes}"])
+        items.append({"item_id": item_id, "status": status, "role": role, "criterion": criterion, "reason": reason, "supersedes": supersedes, "text": item_text})
 
     text = _replace_concrete_work_items_section(text, items)
     text = _append_phase_event(text, phase=f"workitem:{item_id}", status=status, role=role, note=item_text or None)
@@ -1469,6 +1505,10 @@ def _progression_record_errors(
     if not work_items:
         errors.append("at least one concrete work item is required before closure")
     for item in work_items:
+        if item.get("supersedes") and not any(previous["item_id"] == item["supersedes"] for previous in work_items):
+            errors.append(f"work item {item['item_id']} supersedes missing work item {item['supersedes']}")
+        if item.get("supersedes") == item["item_id"]:
+            errors.append(f"work item {item['item_id']} cannot supersede itself")
         if not item.get("criterion"):
             if item["status"] in {"unknown", "blocked", "escalated"} and item.get("reason"):
                 pass

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.2
+Version: 0.4.4
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -126,7 +126,36 @@ reason instead of inventing a criterion.
 
 ## Quick Start
 
-Install the package and initialize an instance:
+### Install from PyPI
+
+XRefKit requires Python 3.11 or later. For a normal installation, create a
+virtual environment and install the published package from PyPI:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+If the `xrefkit` command is not available on `PATH`, use the module form:
+
+```powershell
+python -m xrefkit --help
+```
+
+To use the integrated MCP server, install the optional MCP dependencies:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### Install from a checkout
+
+For XRefKit development, install the local checkout in editable mode instead:
 
 ```powershell
 python -m pip install -e .
@@ -140,6 +169,25 @@ Start the integrated MCP server over stdio:
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+To import existing Skills and prepare a reviewable VS Code MCP setup, run:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp setup `
+  --repo C:\dev\itsm\XRefKit `
+  --import C:\work\existing-skills
+```
+
+The command writes `SETUP.md`, `import-report.json`, a VS Code
+`.vscode/mcp.json` example, and reviewed append text for `AGENTS.md` and
+`CLAUDE.md` into a temporary setup folder. Apply those artifacts after review:
+
+```powershell
+xrefkit mcp setup apply `
+  --source C:\Users\<user>\AppData\Local\Temp\xrefkit-setup-<id> `
+  --repo C:\dev\itsm\XRefKit
+```
+
 The server writes structured correlation events to
 `work/mcp/xid_audit.jsonl` by default. After `xrefkit skill run` returns a
 `run_id`, the client calls MCP `bind_skill_run` and executes the returned

{xrefkit-0.4.2 → xrefkit-0.4.4}/xrefkit.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ tests/test_gate.py
 tests/test_goal_desired_state.py
 tests/test_instruction_workflow.py
 tests/test_knowledge_relations_validator.py
+tests/test_mcp_setup.py
 tests/test_ownership.py
 tests/test_packmeta.py
 tests/test_project_quality_baseline.py
@@ -84,6 +85,7 @@ xrefkit/mcp/ownership.py
 xrefkit/mcp/repository.py
 xrefkit/mcp/schemas.py
 xrefkit/mcp/server.py
+xrefkit/mcp/setup.py
 xrefkit/mcp/startup_contract_pack.py
 xrefkit/models/__init__.py
 xrefkit/models/common.py