xrefkit 0.6.3__tar.gz → 0.7.1__tar.gz

xrefkit-0.7.1/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: xrefkit
+Version: 0.7.1
+Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
+Author: synthaicode
+License: MIT License
+        
+        Copyright (c) 2026 Ritu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.2
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0.0; extra == "mcp"
+Requires-Dist: uvicorn>=0.30; extra == "mcp"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Dynamic: license-file
+
+# XRefKit
+
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/xrefkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/xrefkit)
+
+**Less effort reconstructing AI work. More attention for the decisions that matter.**
+
+XRefKit is designed to reduce the cognitive load of directing and reviewing
+AI-assisted work. It keeps reusable procedures, relevant knowledge, progress,
+and evidence in explicit records, then helps present results in a form people
+can understand and check.
+
+![Five sources of cognitive load and XRefKit's supporting mechanisms, with reports connecting conclusion, evidence, limits, and next action.](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+## Why faster AI output can still mean more work for you
+
+Generating a result leaves another task: understanding enough of it to decide
+whether to use it. You may have to reconstruct the context, identify claims,
+find supporting sources, and check the revised output again. Faster generation
+can leave you with more material to review and more connections to reconstruct.
+
+XRefKit addresses five recurring sources of that effort:
+
+- **You have to remember what to tell the AI.** Rebuilding instructions from
+  memory makes you responsible for recalling every step and criterion.
+  **Reusable Skills** keep the procedure, required inputs, expected outputs,
+  and criteria available for the next task.
+- **You have to search for the rules behind a result.** Scattered reference
+  material makes you switch between documents and reconnect them yourself.
+  Separate **Knowledge** records and stable identifiers (**XIDs**) let a Skill
+  resolve relevant material and record references for review.
+- **You have to rebuild context after an interruption.** A conversation history
+  leaves you to discover where the work stopped.
+  **Work items and handoff records** preserve progress, open concerns, and next
+  steps that another session or colleague can pick up.
+- **You have to learn how to read each new report.** Changing headings, order,
+  or detail makes you search again for the same information.
+  **Optional approved report profiles** preserve familiar structure and
+  granularity, giving subsequent reviews an explicit baseline.
+- **You have to infer what “done” actually covers.** A completion statement can
+  leave the checks, evidence, and unresolved decisions unclear.
+  **Workflow-record checks and reporting guidance** make those boundaries
+  explicit, while tests and reviewers assess the result itself.
+
+The aim is to keep what you need visible and available, so you can check it
+without remembering or reconstructing it each time. How much these mechanisms
+reduce the effort in practice still needs evaluation with users.
+
+## Make the report easier to understand—and easier to check
+
+A shorter report only helps if it preserves what the reader needs to decide.
+XRefKit's reporting guidance connects the conclusion, its basis, its limits,
+and the next action within the task's own format:
+
+- **Reduce searching:** put the conclusion and requested decision first.
+  Keep material uncertainty beside the claim it qualifies.
+- **Reduce mental reconstruction:** connect a finding to its evidence and
+  explain why that evidence matters. A file list alone leaves that connection
+  for the reader to make.
+- **Reduce initial overload:** present the decision-relevant summary, with
+  clear links to detailed findings, so you can inspect the supporting detail
+  when needed. Keep essential caveats in the summary.
+- **Reduce relearning:** for recurring outputs, use an approved Knowledge
+  quality profile containing examples, headings, table structure, information
+  placement, detail, and criteria. Structural checks detect format differences;
+  independent review still judges meaning and evidential support.
+
+For illustration, a change-review summary could read:
+
+> **Decision needed:** Hold acceptance until the retry case is checked.
+>
+> **Verified:** The normal path passed against the agreed criteria; the findings
+> link to the test evidence.
+>
+> **Still unknown:** Whether retrying after a timeout creates a duplicate.
+>
+> **Next step:** Test the retry case and return the result for review.
+
+This example shows where the reader's attention belongs; it is not a universal
+template or a real test result. Plain words, short sections, and clear connections
+between a finding and its evidence help you follow the reasoning.
+
+Reader feedback can identify a missing explanation, confusing placement, or
+insufficient evidence. The correction can then target the output, inputs,
+criteria, or procedure. Approved baselines stay intact; procedure changes require
+explicit authorization.
+
+The purpose is to make informed review less demanding. A familiar layout or a
+passing record check does not establish correctness. See the
+[reporting contract](docs/core/contracts/081_skill_reporting_contract.md#xid-6B2D9F4A1C73)
+and [fixed-output quality protocol](docs/core/contracts/112_fixed_output_quality_protocol.md#xid-F9C2A8D471B0).
+
+## How does XRefKit fit with modern agent harnesses?
+
+Modern harnesses already support more than execution. They can preserve sessions,
+organize repository knowledge and plans, and support evaluation criteria,
+automated constraints, and structured handoffs. The capabilities available to
+you depend on the harness and its configuration.
+
+XRefKit's focus is the human effort of directing, understanding, and reviewing
+that work. It packages reusable procedures, separately maintained knowledge,
+work records, and reporting criteria as assets the team can inspect and maintain.
+Repository files and Skill Packages preserve those assets; CLI/MCP interfaces
+make them available to compatible clients.
+
+Your coding harness can implement and test a change while XRefKit records the
+applicable review method, references, findings, and open concerns. The report
+then helps a person decide what the result supports and what to do next.
+The client runs the model and tools; XRefKit's `verify` and `close` check
+workflow records, while substantive quality needs appropriate tests and review.
+
+If your harness already provides this structure, there may be little to add.
+Use XRefKit when you want these work assets and review conventions made explicit
+and reusable. This is a difference in packaged mechanisms and emphasis, not a
+demonstrated advantage in cognitive load, quality, cost, or performance.
+
+See the [Skill and Knowledge operating model](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
+and [Skill operating contract](docs/core/contracts/058_skill_operating_contract.md#xid-B7A2C94F0E61).
+
+## Start with one recurring task
+
+Choose a task you already know how to review: a document check, an investigation,
+or a development handoff. Start with one procedure and the reference material it
+needs, then use the resulting work record to decide what to improve.
+
+### 1. Prepare your workspace
+
+You need Python 3.11 or later. Run these commands in the folder where you want to work:
+
+```powershell
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+Initialization creates the local XRefKit configuration and missing AI startup
+files while preserving existing startup files. See the
+[installation and Skill Package guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
+to add reusable Skills or bring existing material into your workspace.
+
+For older custom Skills that call Python under a shared `tools/` directory,
+connect your AI client and ask it to migrate the old environment. See
+[guided legacy migration](docs/guides/117_guided_legacy_python_migration.md#xid-6D73C9A12E40)
+for preparation, safe baseline tests, governed registration and client verification.
+
+### 2. Connect your AI tool
+
+For VS Code/Copilot, install the optional MCP integration and generate a setup proposal:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+python -m xrefkit mcp setup --repo . --output .xrefkit/setup-review
+```
+
+Review the generated files, then apply the setup:
+
+```powershell
+python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review
+```
+
+Open the workspace in VS Code, start the `xrefkit` MCP server, and ask in Copilot chat:
+
+> Call XRefKit's get_startup_context and help me get started.
+
+Then describe the task you want to accomplish. You do not need to know a Skill
+name to ask for guidance. Opening VS Code alone does not start the conversation.
+
+For an MCP client that accepts a local server command, the server entry point is:
+
+```powershell
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### 3. Review the work and decide what comes next
+
+Use the [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
+to inspect recorded progress, referenced knowledge, outputs, concerns, and
+handoffs. It shows what was recorded and where observations are missing; you
+decide whether the result is ready to use.
+
+The [workflow walkthrough](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
+explains how work moves from a request to verification and handoff.
+
+## Choose your next step
+
+- **Use existing procedures:** [Install and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+- **Organize a task from your own instructions:** [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60).
+- **Capture your team's way of working:** [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8), then [author a Skill](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B).
+- **Explore the details:** [Browse the documentation](docs/000_index.md#xid-56DD6EB68343).
+
+## Optional: explore model fit with Attention Pet
+
+The experimental [Attention Pet](projects/attention-pet/README.en.md) companion
+helps Codex users inspect estimates of model suitability and compare lower-cost
+candidates using the visible work context. Run it from a Codex terminal in this repository:
+
+```powershell
+python -m xrefkit.attention_pet serve --port 8769
+```
+
+Open the printed address in the Codex browser panel. The preview follows the chat
+that launched it. Its estimates are uncalibrated; it does not measure internal
+attention or token usage, and it does not change your model settings.
+
+## Contribute or maintain a deployment
+
+For local development, install this checkout with `python -m pip install -e .`.
+The [pipeline dependency reference](docs/reference/125_pipeline_dependency_matrix.md#xid-7E4B19C2A860)
+describes CI and publication triggers. Internal authoring and runtime details are
+in the [SkillDefinition contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
+and [Workflow Runtime Binding contract](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F).
+
+XRefKit does not require provider API keys to install or explore the package.
+Authenticate your AI tool through its provider's supported methods, and keep
+secrets and access tokens out of the repository.

xrefkit-0.7.1/README.md

@@ -0,0 +1,214 @@
+# XRefKit
+
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/xrefkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/xrefkit)
+
+**Less effort reconstructing AI work. More attention for the decisions that matter.**
+
+XRefKit is designed to reduce the cognitive load of directing and reviewing
+AI-assisted work. It keeps reusable procedures, relevant knowledge, progress,
+and evidence in explicit records, then helps present results in a form people
+can understand and check.
+
+![Five sources of cognitive load and XRefKit's supporting mechanisms, with reports connecting conclusion, evidence, limits, and next action.](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+## Why faster AI output can still mean more work for you
+
+Generating a result leaves another task: understanding enough of it to decide
+whether to use it. You may have to reconstruct the context, identify claims,
+find supporting sources, and check the revised output again. Faster generation
+can leave you with more material to review and more connections to reconstruct.
+
+XRefKit addresses five recurring sources of that effort:
+
+- **You have to remember what to tell the AI.** Rebuilding instructions from
+  memory makes you responsible for recalling every step and criterion.
+  **Reusable Skills** keep the procedure, required inputs, expected outputs,
+  and criteria available for the next task.
+- **You have to search for the rules behind a result.** Scattered reference
+  material makes you switch between documents and reconnect them yourself.
+  Separate **Knowledge** records and stable identifiers (**XIDs**) let a Skill
+  resolve relevant material and record references for review.
+- **You have to rebuild context after an interruption.** A conversation history
+  leaves you to discover where the work stopped.
+  **Work items and handoff records** preserve progress, open concerns, and next
+  steps that another session or colleague can pick up.
+- **You have to learn how to read each new report.** Changing headings, order,
+  or detail makes you search again for the same information.
+  **Optional approved report profiles** preserve familiar structure and
+  granularity, giving subsequent reviews an explicit baseline.
+- **You have to infer what “done” actually covers.** A completion statement can
+  leave the checks, evidence, and unresolved decisions unclear.
+  **Workflow-record checks and reporting guidance** make those boundaries
+  explicit, while tests and reviewers assess the result itself.
+
+The aim is to keep what you need visible and available, so you can check it
+without remembering or reconstructing it each time. How much these mechanisms
+reduce the effort in practice still needs evaluation with users.
+
+## Make the report easier to understand—and easier to check
+
+A shorter report only helps if it preserves what the reader needs to decide.
+XRefKit's reporting guidance connects the conclusion, its basis, its limits,
+and the next action within the task's own format:
+
+- **Reduce searching:** put the conclusion and requested decision first.
+  Keep material uncertainty beside the claim it qualifies.
+- **Reduce mental reconstruction:** connect a finding to its evidence and
+  explain why that evidence matters. A file list alone leaves that connection
+  for the reader to make.
+- **Reduce initial overload:** present the decision-relevant summary, with
+  clear links to detailed findings, so you can inspect the supporting detail
+  when needed. Keep essential caveats in the summary.
+- **Reduce relearning:** for recurring outputs, use an approved Knowledge
+  quality profile containing examples, headings, table structure, information
+  placement, detail, and criteria. Structural checks detect format differences;
+  independent review still judges meaning and evidential support.
+
+For illustration, a change-review summary could read:
+
+> **Decision needed:** Hold acceptance until the retry case is checked.
+>
+> **Verified:** The normal path passed against the agreed criteria; the findings
+> link to the test evidence.
+>
+> **Still unknown:** Whether retrying after a timeout creates a duplicate.
+>
+> **Next step:** Test the retry case and return the result for review.
+
+This example shows where the reader's attention belongs; it is not a universal
+template or a real test result. Plain words, short sections, and clear connections
+between a finding and its evidence help you follow the reasoning.
+
+Reader feedback can identify a missing explanation, confusing placement, or
+insufficient evidence. The correction can then target the output, inputs,
+criteria, or procedure. Approved baselines stay intact; procedure changes require
+explicit authorization.
+
+The purpose is to make informed review less demanding. A familiar layout or a
+passing record check does not establish correctness. See the
+[reporting contract](docs/core/contracts/081_skill_reporting_contract.md#xid-6B2D9F4A1C73)
+and [fixed-output quality protocol](docs/core/contracts/112_fixed_output_quality_protocol.md#xid-F9C2A8D471B0).
+
+## How does XRefKit fit with modern agent harnesses?
+
+Modern harnesses already support more than execution. They can preserve sessions,
+organize repository knowledge and plans, and support evaluation criteria,
+automated constraints, and structured handoffs. The capabilities available to
+you depend on the harness and its configuration.
+
+XRefKit's focus is the human effort of directing, understanding, and reviewing
+that work. It packages reusable procedures, separately maintained knowledge,
+work records, and reporting criteria as assets the team can inspect and maintain.
+Repository files and Skill Packages preserve those assets; CLI/MCP interfaces
+make them available to compatible clients.
+
+Your coding harness can implement and test a change while XRefKit records the
+applicable review method, references, findings, and open concerns. The report
+then helps a person decide what the result supports and what to do next.
+The client runs the model and tools; XRefKit's `verify` and `close` check
+workflow records, while substantive quality needs appropriate tests and review.
+
+If your harness already provides this structure, there may be little to add.
+Use XRefKit when you want these work assets and review conventions made explicit
+and reusable. This is a difference in packaged mechanisms and emphasis, not a
+demonstrated advantage in cognitive load, quality, cost, or performance.
+
+See the [Skill and Knowledge operating model](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
+and [Skill operating contract](docs/core/contracts/058_skill_operating_contract.md#xid-B7A2C94F0E61).
+
+## Start with one recurring task
+
+Choose a task you already know how to review: a document check, an investigation,
+or a development handoff. Start with one procedure and the reference material it
+needs, then use the resulting work record to decide what to improve.
+
+### 1. Prepare your workspace
+
+You need Python 3.11 or later. Run these commands in the folder where you want to work:
+
+```powershell
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+Initialization creates the local XRefKit configuration and missing AI startup
+files while preserving existing startup files. See the
+[installation and Skill Package guide](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
+to add reusable Skills or bring existing material into your workspace.
+
+For older custom Skills that call Python under a shared `tools/` directory,
+connect your AI client and ask it to migrate the old environment. See
+[guided legacy migration](docs/guides/117_guided_legacy_python_migration.md#xid-6D73C9A12E40)
+for preparation, safe baseline tests, governed registration and client verification.
+
+### 2. Connect your AI tool
+
+For VS Code/Copilot, install the optional MCP integration and generate a setup proposal:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+python -m xrefkit mcp setup --repo . --output .xrefkit/setup-review
+```
+
+Review the generated files, then apply the setup:
+
+```powershell
+python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review
+```
+
+Open the workspace in VS Code, start the `xrefkit` MCP server, and ask in Copilot chat:
+
+> Call XRefKit's get_startup_context and help me get started.
+
+Then describe the task you want to accomplish. You do not need to know a Skill
+name to ask for guidance. Opening VS Code alone does not start the conversation.
+
+For an MCP client that accepts a local server command, the server entry point is:
+
+```powershell
+xrefkit mcp serve --repo . --transport stdio
+```
+
+### 3. Review the work and decide what comes next
+
+Use the [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
+to inspect recorded progress, referenced knowledge, outputs, concerns, and
+handoffs. It shows what was recorded and where observations are missing; you
+decide whether the result is ready to use.
+
+The [workflow walkthrough](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
+explains how work moves from a request to verification and handoff.
+
+## Choose your next step
+
+- **Use existing procedures:** [Install and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90).
+- **Organize a task from your own instructions:** [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60).
+- **Capture your team's way of working:** [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8), then [author a Skill](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B).
+- **Explore the details:** [Browse the documentation](docs/000_index.md#xid-56DD6EB68343).
+
+## Optional: explore model fit with Attention Pet
+
+The experimental [Attention Pet](projects/attention-pet/README.en.md) companion
+helps Codex users inspect estimates of model suitability and compare lower-cost
+candidates using the visible work context. Run it from a Codex terminal in this repository:
+
+```powershell
+python -m xrefkit.attention_pet serve --port 8769
+```
+
+Open the printed address in the Codex browser panel. The preview follows the chat
+that launched it. Its estimates are uncalibrated; it does not measure internal
+attention or token usage, and it does not change your model settings.
+
+## Contribute or maintain a deployment
+
+For local development, install this checkout with `python -m pip install -e .`.
+The [pipeline dependency reference](docs/reference/125_pipeline_dependency_matrix.md#xid-7E4B19C2A860)
+describes CI and publication triggers. Internal authoring and runtime details are
+in the [SkillDefinition contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
+and [Workflow Runtime Binding contract](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F).
+
+XRefKit does not require provider API keys to install or explore the package.
+Authenticate your AI tool through its provider's supported methods, and keep
+secrets and access tokens out of the repository.

{xrefkit-0.6.3 → xrefkit-0.7.1}/pyproject.toml

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

xrefkit-0.7.1/tests/test_ci_workflow_invariants.py

@@ -0,0 +1,190 @@
+"""CI cleanup must retain release coverage and only cancel obsolete PR runs."""
+from pathlib import Path
+
+import pytest
+import yaml
+
+
+WORKFLOWS = Path(__file__).resolve().parents[1] / ".github/workflows"
+PACKAGES = {
+    "python-package.yml": ("Core", "v*.*.*", {"sdist-install-smoke", "skill-compatibility"}),
+    "python-skill-brownfield-package.yml": (
+        "Brownfield", "xrefkit-skills-brownfield-v*.*.*", {"sdist-install-smoke"}),
+    "python-skill-csharp-package.yml": ("CSharp", "xrefkit-skills-csharp-v*.*.*", set()),
+    "python-skill-batch-regression-package.yml": (
+        "Batch regression", "xrefkit-skills-batch-regression-v*.*.*", {"sdist-install-smoke"}),
+}
+
+
+def workflow(filename):
+    # BaseLoader preserves GitHub's `on` key instead of YAML 1.1's boolean True.
+    return yaml.load((WORKFLOWS / filename).read_text(encoding="utf-8"), Loader=yaml.BaseLoader)
+
+
+def test_core_full_quality_gate_runs_once_and_retains_security():
+    matches = []
+    for path in WORKFLOWS.glob("*.yml"):
+        for job_id, job in workflow(path.name).get("jobs", {}).items():
+            for step in job.get("steps", []):
+                if "python tools/run_quality_gate.py xrefkit" in step.get("run", ""):
+                    matches.append((path.name, job_id))
+    assert matches == [("python-package.yml", "quality")]
+    runs = "\n".join(step.get("run", "") for step in workflow("python-package.yml")["jobs"]["quality"]["steps"])
+    assert '".[test,mcp]"' in runs
+    assert 'bandit -r "${PYTHON_SOURCE_ROOT}" -ll' in runs
+    assert "-r requirements.txt" in runs and "--local" in runs and "--skip-editable" in runs
+    slides = workflow("xref-check.yml")
+    assert set(slides["jobs"]) == {"slides-app-quality"}
+    assert any("run_quality_gate.py slides-app --install-node-deps" in step.get("run", "")
+               for step in slides["jobs"]["slides-app-quality"]["steps"])
+
+
+@pytest.mark.parametrize("filename", [*PACKAGES, "xref-check.yml"])
+def test_only_superseded_pull_request_runs_are_canceled(filename):
+    data = workflow(filename)
+    assert data["concurrency"] == {
+        "group": "${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.run_id }}",
+        "cancel-in-progress": "${{ github.event_name == 'pull_request' }}",
+    }
+    assert "pull_request" in data["on"]
+    if filename in {"python-package.yml", "xref-check.yml"}:
+        assert data["on"]["push"]["branches"] == ["main"]
+    else:
+        assert "branches" not in data["on"]["push"]
+
+
+@pytest.mark.parametrize("filename", PACKAGES)
+def test_release_gates_and_unique_target_names_are_retained(filename):
+    prefix, tag, extra_gates = PACKAGES[filename]
+    data = workflow(filename)
+    jobs = data["jobs"]
+    gates = {"quality", "build-distribution", "artifact-inspection", "install-smoke-test"} | extra_gates
+    assert set(jobs) == gates | {"publish-to-pypi"}
+    assert set(jobs["publish-to-pypi"]["needs"]) == gates
+    for job_id in gates - {"quality", "build-distribution"}:
+        assert jobs[job_id]["needs"] == "build-distribution"
+    assert data["on"]["push"]["tags"] == [tag]
+    assert jobs["publish-to-pypi"]["if"] == (
+        "github.event_name == 'push' && startsWith(github.ref, 'refs/tags/" + tag.split("*")[0] + "')")
+    assert jobs["publish-to-pypi"]["permissions"]["id-token"] == "write"
+    assert data["permissions"] == {"contents": "read"}
+    names = [job["name"] for job in jobs.values()]
+    assert len(set(names)) == len(names)
+    assert all(name.startswith(prefix + " / ") for name in names)
+
+
+def accepts_changes(filename, event, files):
+    from fnmatch import fnmatchcase
+
+    config = workflow(filename)["on"].get(event)
+    if config is None:
+        return False
+    if not isinstance(config, dict):
+        return True
+    if "paths" in config:
+        return any(fnmatchcase(path, pattern) for path in files for pattern in config["paths"])
+    return any(not any(fnmatchcase(path, pattern) for pattern in config.get("paths-ignore", []))
+               for path in files)
+
+
+@pytest.mark.parametrize("filename", [*PACKAGES, "xref-check.yml", "pages.yml",
+                                      "xrefkit-skills-xddp-design.yml"])
+def test_readme_only_changes_skip_unrelated_workflows(filename):
+    for event in ("pull_request", "push"):
+        # Tag pushes deliberately do not evaluate GitHub path filters.
+        if event == "push" and "branches" not in workflow(filename)["on"].get(event, {}):
+            continue
+        assert not accepts_changes(filename, event, ["README.md"])
+
+
+@pytest.mark.parametrize("path", ["xrefkit/cli.py", "docs/core/contracts/example.md",
+                                  "skills/example/SKILL.v1.md", "knowledge/example.md",
+                                  "agent/000_agent_entry.md", "tests/test_example.py"])
+def test_readme_exclusion_retains_core_and_governance_checks(path):
+    for event in ("pull_request", "push"):
+        assert accepts_changes("python-package.yml", event, [path])
+        assert accepts_changes("python-package.yml", event, ["README.md", path])
+    assert workflow("python-package.yml")["on"]["pull_request"]["paths"] == workflow("python-package.yml")["on"]["push"]["paths"]
+    assert "README.md" not in workflow("python-package.yml")["on"]["push"]["paths"]
+
+
+@pytest.mark.parametrize("package", ["batch-regression", "brownfield", "csharp"])
+def test_skill_packages_cover_own_sources_and_shared_dependencies(package):
+    filename = f"python-skill-{package}-package.yml"
+    for path in [f"packages/xrefkit-skills-{package}/tests/test_package.py",
+                 f".github/workflows/{filename}", "tools/inspect_python_artifacts.py"]:
+        assert accepts_changes(filename, "pull_request", [path])
+    if package in {"brownfield", "batch-regression"}:
+        assert accepts_changes(filename, "pull_request", ["tools/run_import_smoke.py"])
+    for path in ["projects/slides-app/src/App.tsx", "xrefkit/workspace.py",
+                 "pyproject.toml", "requirements.txt", "docs/core/contracts/example.md"]:
+        assert not accepts_changes(filename, "pull_request", [path])
+        assert accepts_changes(filename, "pull_request", [path, f"packages/xrefkit-skills-{package}/pyproject.toml"])
+
+
+def test_slides_inputs_and_pages_manifest_inputs_are_covered():
+    import json
+
+    for event in ("pull_request", "push"):
+        for path in ["projects/slides-app/package.json", "tools/run_quality_gate.py",
+                     "requirements.txt", ".github/workflows/xref-check.yml"]:
+            assert accepts_changes("xref-check.yml", event, [path])
+        assert not accepts_changes("xref-check.yml", event, ["xrefkit/cli.py"])
+    manifest = json.loads((WORKFLOWS.parents[1] / "site/source_manifest.json").read_text())
+    for tree in manifest["trees"]:
+        assert accepts_changes("pages.yml", "push", [tree["source"] + "/index.html"])
+    for path in ["site/source_manifest.json", "site/index.html", "tools/site_build.py",
+                 "tools/site_release_metadata.py", ".github/workflows/pages.yml"]:
+        assert accepts_changes("pages.yml", "push", [path])
+    assert not accepts_changes("pages.yml", "push", ["human-docs/ja/unrelated.md"])
+    data = workflow("pages.yml")
+    assert {"release", "workflow_run", "workflow_dispatch"} <= set(data["on"])
+    condition = data["jobs"]["deploy"]["if"]
+    assert "github.event.workflow_run.conclusion == 'success'" in condition
+    assert "github.event.workflow_run.event == 'push'" in condition
+    assert "startsWith(github.event.workflow_run.head_branch, 'v')" in condition
+    assert "github.event.workflow_run.head_repository.full_name == github.repository" in condition
+
+
+def test_all_workflows_parse_and_sync_still_includes_readme_updates():
+    for path in WORKFLOWS.glob("*.yml"):
+        data = workflow(path.name)
+        assert isinstance(data["on"], dict)
+        assert isinstance(data["jobs"], dict)
+    assert accepts_changes("sync-main-without-mp4.yml", "push", ["README.md"])
+    assert workflow("sync-main-without-mp4.yml")["on"]["push"] == {"branches": ["main"]}
+
+
+@pytest.mark.parametrize("path", [
+    "xrefkit/resources/base/current.json", "tools/check_skill_compatibility.py",
+    "tools/check_installed_skill_contract.py", "tools/official_skill_packages.json",
+    "packages/xrefkit-skills-xddp-design/pyproject.toml", "packages/new-skill/pyproject.toml",
+    "governance/skills/planning_flow.json", "observations/trial_basis.md",
+    "packs/example/skills/example/SKILL.v1.md", "flows/example.yaml",
+    "work/sessions/tracked_run.md", "work/retrospectives/example.md",
+    "site/sources/index.html", "projects/attention-pet/schema/fit.schema.json",
+    "projects/new-app/package.json", "projects/new-app/package-lock.json",
+    "projects/new-app/README.md", "ownership.yaml", "xrefkit.toml", "LICENSE",
+    ".gitattributes", ".gitignore", ".github/workflows/pages.yml",
+])
+def test_core_dependency_inputs_trigger_branch_and_pr_checks(path):
+    for event in ("pull_request", "push"):
+        assert accepts_changes("python-package.yml", event, [path])
+
+
+@pytest.mark.parametrize("path", ["README.md", "CHANGELOG.md", "human-docs/ja/article.md",
+                                  "projects/slides-app/src/App.tsx", "work/plans/example.md",
+                                  "sources/unconsumed.pdf"])
+def test_unconsumed_inputs_do_not_trigger_core_but_mixed_changes_do(path):
+    for event in ("pull_request", "push"):
+        assert not accepts_changes("python-package.yml", event, [path])
+        assert accepts_changes("python-package.yml", event, [path, "xrefkit/cli.py"])
+
+
+def test_shared_tools_trigger_only_consumers():
+    assert accepts_changes("python-package.yml", "pull_request", ["tools/inspect_python_artifacts.py"])
+    for filename in list(PACKAGES)[1:] + ["xrefkit-skills-xddp-design.yml"]:
+        assert accepts_changes(filename, "pull_request", ["tools/inspect_python_artifacts.py"])
+        assert not accepts_changes(filename, "pull_request", ["tools/run_quality_gate.py"])
+    assert not accepts_changes("python-skill-csharp-package.yml", "pull_request", ["tools/run_import_smoke.py"])
+    assert not accepts_changes("xrefkit-skills-xddp-design.yml", "pull_request", ["xrefkit/cli.py"])