xrefkit 0.3.0__tar.gz

xrefkit-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+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.

xrefkit-0.3.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: xrefkit
+Version: 0.3.0
+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>=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
+
+AI agents often stop halfway, guess missing context, or produce work that looks
+plausible but cannot be reviewed or handed off.
+
+XRefKit is a portable Python package and repository model for AI-assisted work
+that must reproduce domain procedures and judgments.
+
+It runs as its own control repository and helps AI agents:
+
+- load the right knowledge before acting
+- select reusable Skills
+- record judgments and evidence
+- preserve handoffs across humans, agents, and sessions
+- close work only through explicit quality gates
+
+The package provides XID resolution, compact runtime contracts, Skill execution,
+catalog-first context loading, deterministic closure gates, client-side tools,
+and a thin MCP adapter over the same rules.
+
+▶️ Download the 2-minute overview: [Why XRefKit exists and how it helps AI teams use domain knowledge](https://raw.githubusercontent.com/synthaicode/XRefKit/main/readme.mp4)
+
+## Security and API Keys
+
+XRefKit does not require Claude, OpenAI, GitHub, or other provider API keys to explore the repository.
+
+This repository is a governance and knowledge-operations framework for AI-assisted work. It does not ask users to paste API keys into the repository, issue trackers, prompts, or configuration files.
+
+If you use XRefKit with an external AI agent such as Claude Code, Codex, or GitHub Copilot, authenticate that agent through the official provider mechanism outside this repository.
+
+Do not commit secrets, API keys, access tokens, `.env` files, or provider credentials to this repository.
+
+XRefKit does not include repository-managed Claude settings, hooks, MCP server auto-approval, or provider endpoint redirection.
+
+Before running any AI agent in this repository, review agent startup files and tool settings. XRefKit treats repository-controlled agent configuration as part of the trust boundary.
+
+## The Problem
+
+Using AI for real work creates recurring operating problems:
+
+![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+- the AI can act from incomplete context or unsupported guesses
+- procedures, domain facts, and judgment criteria get mixed together in prompts
+- execution, checking, and handoff collapse into one opaque step
+- work becomes hard to continue across agents, humans, or sessions
+- outputs may lack evidence, closure discipline, or auditability
+
+## What XRefKit Provides
+
+XRefKit makes AI work explicit by separating:
+
+- Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
+- Knowledge: source-backed domain facts and local rules loaded only when needed
+- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
+- Evidence: logs, judgments, concerns, and quality checks
+- XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
+
+This separation prevents prompts, domain facts, execution steps, review criteria,
+and handoff records from collapsing into one opaque instruction block.
+
+![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
+
+## How It Works
+
+1. Original materials are kept in `sources/`.
+2. AI-readable knowledge is maintained in `knowledge/`.
+3. Work is defined in `skills/` (executable procedure with a capability/tuning/responsibility identity) and `knowledge/`.
+4. Agents are routed semantically to the right Skill and load only the relevant context.
+5. Evidence and quality gates make incomplete or unsupported work visible.
+
+## Quick Start
+
+Install the package and initialize an instance:
+
+```powershell
+python -m pip install -e .
+xrefkit init
+xrefkit --help
+```
+
+Start the integrated MCP server over stdio:
+
+```powershell
+xrefkit mcp serve --repo . --transport stdio
+```
+
+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
+`client_record_command` against the local `run_log`. Subsequent MCP Knowledge
+searches and XID resolutions then share the same `run_id` as the client Skill
+Run. The client separately records actual model-context loading and judgment
+application with `xrefkit skill knowledge --action load|apply`.
+
+XRefKit is designed to be driven by an AI agent. The agent first resolves the
+startup contract XID, selects a Skill or source target from a compact catalog,
+and expands only the selected body.
+
+Here, `sources/` is the human drop point for original materials, existing Skill artifacts, rules, and examples that the AI will turn into repository-managed assets.
+
+If you are migrating an existing Skill:
+
+1. Place the source Skill or related source materials in `sources/`.
+2. Ask the AI agent to migrate that Skill into the XRefKit repository model.
+3. Have the migration process separate procedure, source-backed knowledge, and runtime structure as needed.
+4. Review whether the migrated Skill is usable for the intended work.
+
+If you are creating a new Skill:
+
+1. Place the source materials, rules, or task examples in `sources/`.
+2. Ask the AI agent to use the Skill authoring flow (`skill_flow_authoring`) to create a new Skill.
+3. Have the authoring process separate procedure, source-backed knowledge, and runtime structure as needed.
+4. Review whether the new Skill is usable for the intended work.
+
+In both cases:
+
+1. Give the AI agent a concrete work request with the goal, expected output, and constraints.
+2. Inspect `work/` records as operational memory, then refine the Skill, knowledge, guard conditions, routing rules, and quality gates based on what happened.
+
+## How to Explore This Repository
+
+Point your AI agent at this repository and ask directly.
+
+Startup instruction files for Claude, Codex, and GitHub Copilot are included.
+
+These files are plain-text operating instructions. They do not contain API keys, provider credentials, hooks, MCP server definitions, or network redirection settings.
+
+The agent can read the operating contract and explain the repository structure in context.
+
+## Repository Map
+
+- `xrefkit/`: installable runtime, resolver, Skill control, tools registry, and MCP adapter
+- `docs/`: human-facing docs and policy
+- `knowledge/`: source-backed knowledge fragments
+- `sources/`: original materials for verification
+- `skills/`: Skill definitions and routing index
+- `tools/`: XID-backed client-side command implementations and packaged assets
+- `work/`: operational memory for execution logs, judgments, handoffs, retrospectives, and improvement input
+- `agent/`: agent entry and operating contract
+- `human-docs/`: human-facing Japanese and English docs, materials, assets, and video packages
+- `site/`: generated publication output, source manifest, and compatibility routes
+
+## Runtime and Context Model
+
+- Base runtime obligations are authored structurally and compiled into package resources with source hashes and token budgets.
+- Repository, installed-package, and MCP providers resolve the same XID identities; conflicts and stale base packs fail explicitly.
+
+The installed base runtime pack is generation-published. Formal consumers must
+read `xrefkit/resources/base/current.json` first and then load both files from
+the referenced `generations/<generation>/` directory. The top-level
+`contracts.json` and `model_body.md` files are compatibility snapshots only;
+they are not an authoritative source and must not be used for generation
+consistency checks.
+- Source structure is split into a target catalog and finding catalog. The AI loads lists before selected details.
+- `xrefkit catalog maintain --apply-safe` promotes only unambiguous candidate findings; conflicts remain in a review queue.
+- MCP exposes the shared resolver and catalogs. It does not own independent domain rules or execute client tools.
+
+## Entry Points
+
+- Human documentation: `docs/000_index.md`
+- Human-facing language trees: `human-docs/ja/000_index.md`, `human-docs/en/`
+- Agent entry: `agent/000_agent_entry.md`

xrefkit-0.3.0/README.md

@@ -0,0 +1,164 @@
+# XRefKit
+
+AI agents often stop halfway, guess missing context, or produce work that looks
+plausible but cannot be reviewed or handed off.
+
+XRefKit is a portable Python package and repository model for AI-assisted work
+that must reproduce domain procedures and judgments.
+
+It runs as its own control repository and helps AI agents:
+
+- load the right knowledge before acting
+- select reusable Skills
+- record judgments and evidence
+- preserve handoffs across humans, agents, and sessions
+- close work only through explicit quality gates
+
+The package provides XID resolution, compact runtime contracts, Skill execution,
+catalog-first context loading, deterministic closure gates, client-side tools,
+and a thin MCP adapter over the same rules.
+
+▶️ Download the 2-minute overview: [Why XRefKit exists and how it helps AI teams use domain knowledge](https://raw.githubusercontent.com/synthaicode/XRefKit/main/readme.mp4)
+
+## Security and API Keys
+
+XRefKit does not require Claude, OpenAI, GitHub, or other provider API keys to explore the repository.
+
+This repository is a governance and knowledge-operations framework for AI-assisted work. It does not ask users to paste API keys into the repository, issue trackers, prompts, or configuration files.
+
+If you use XRefKit with an external AI agent such as Claude Code, Codex, or GitHub Copilot, authenticate that agent through the official provider mechanism outside this repository.
+
+Do not commit secrets, API keys, access tokens, `.env` files, or provider credentials to this repository.
+
+XRefKit does not include repository-managed Claude settings, hooks, MCP server auto-approval, or provider endpoint redirection.
+
+Before running any AI agent in this repository, review agent startup files and tool settings. XRefKit treats repository-controlled agent configuration as part of the trust boundary.
+
+## The Problem
+
+Using AI for real work creates recurring operating problems:
+
+![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+- the AI can act from incomplete context or unsupported guesses
+- procedures, domain facts, and judgment criteria get mixed together in prompts
+- execution, checking, and handoff collapse into one opaque step
+- work becomes hard to continue across agents, humans, or sessions
+- outputs may lack evidence, closure discipline, or auditability
+
+## What XRefKit Provides
+
+XRefKit makes AI work explicit by separating:
+
+- Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
+- Knowledge: source-backed domain facts and local rules loaded only when needed
+- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
+- Evidence: logs, judgments, concerns, and quality checks
+- XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
+
+This separation prevents prompts, domain facts, execution steps, review criteria,
+and handoff records from collapsing into one opaque instruction block.
+
+![XRefKit repository snapshot](human-docs/en/assets/xrefkit_repository_snapshot/xrefkit_repository_snapshot.png)
+
+## How It Works
+
+1. Original materials are kept in `sources/`.
+2. AI-readable knowledge is maintained in `knowledge/`.
+3. Work is defined in `skills/` (executable procedure with a capability/tuning/responsibility identity) and `knowledge/`.
+4. Agents are routed semantically to the right Skill and load only the relevant context.
+5. Evidence and quality gates make incomplete or unsupported work visible.
+
+## Quick Start
+
+Install the package and initialize an instance:
+
+```powershell
+python -m pip install -e .
+xrefkit init
+xrefkit --help
+```
+
+Start the integrated MCP server over stdio:
+
+```powershell
+xrefkit mcp serve --repo . --transport stdio
+```
+
+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
+`client_record_command` against the local `run_log`. Subsequent MCP Knowledge
+searches and XID resolutions then share the same `run_id` as the client Skill
+Run. The client separately records actual model-context loading and judgment
+application with `xrefkit skill knowledge --action load|apply`.
+
+XRefKit is designed to be driven by an AI agent. The agent first resolves the
+startup contract XID, selects a Skill or source target from a compact catalog,
+and expands only the selected body.
+
+Here, `sources/` is the human drop point for original materials, existing Skill artifacts, rules, and examples that the AI will turn into repository-managed assets.
+
+If you are migrating an existing Skill:
+
+1. Place the source Skill or related source materials in `sources/`.
+2. Ask the AI agent to migrate that Skill into the XRefKit repository model.
+3. Have the migration process separate procedure, source-backed knowledge, and runtime structure as needed.
+4. Review whether the migrated Skill is usable for the intended work.
+
+If you are creating a new Skill:
+
+1. Place the source materials, rules, or task examples in `sources/`.
+2. Ask the AI agent to use the Skill authoring flow (`skill_flow_authoring`) to create a new Skill.
+3. Have the authoring process separate procedure, source-backed knowledge, and runtime structure as needed.
+4. Review whether the new Skill is usable for the intended work.
+
+In both cases:
+
+1. Give the AI agent a concrete work request with the goal, expected output, and constraints.
+2. Inspect `work/` records as operational memory, then refine the Skill, knowledge, guard conditions, routing rules, and quality gates based on what happened.
+
+## How to Explore This Repository
+
+Point your AI agent at this repository and ask directly.
+
+Startup instruction files for Claude, Codex, and GitHub Copilot are included.
+
+These files are plain-text operating instructions. They do not contain API keys, provider credentials, hooks, MCP server definitions, or network redirection settings.
+
+The agent can read the operating contract and explain the repository structure in context.
+
+## Repository Map
+
+- `xrefkit/`: installable runtime, resolver, Skill control, tools registry, and MCP adapter
+- `docs/`: human-facing docs and policy
+- `knowledge/`: source-backed knowledge fragments
+- `sources/`: original materials for verification
+- `skills/`: Skill definitions and routing index
+- `tools/`: XID-backed client-side command implementations and packaged assets
+- `work/`: operational memory for execution logs, judgments, handoffs, retrospectives, and improvement input
+- `agent/`: agent entry and operating contract
+- `human-docs/`: human-facing Japanese and English docs, materials, assets, and video packages
+- `site/`: generated publication output, source manifest, and compatibility routes
+
+## Runtime and Context Model
+
+- Base runtime obligations are authored structurally and compiled into package resources with source hashes and token budgets.
+- Repository, installed-package, and MCP providers resolve the same XID identities; conflicts and stale base packs fail explicitly.
+
+The installed base runtime pack is generation-published. Formal consumers must
+read `xrefkit/resources/base/current.json` first and then load both files from
+the referenced `generations/<generation>/` directory. The top-level
+`contracts.json` and `model_body.md` files are compatibility snapshots only;
+they are not an authoritative source and must not be used for generation
+consistency checks.
+- Source structure is split into a target catalog and finding catalog. The AI loads lists before selected details.
+- `xrefkit catalog maintain --apply-safe` promotes only unambiguous candidate findings; conflicts remain in a review queue.
+- MCP exposes the shared resolver and catalogs. It does not own independent domain rules or execute client tools.
+
+## Entry Points
+
+- Human documentation: `docs/000_index.md`
+- Human-facing language trees: `human-docs/ja/000_index.md`, `human-docs/en/`
+- Agent entry: `agent/000_agent_entry.md`

xrefkit-0.3.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xrefkit"
+version = "0.3.0"
+description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "synthaicode" }]
+dependencies = [
+  "PyYAML>=6.0.2,<7",
+  "pydantic>=2.0,<3",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0", "uvicorn>=0.30"]
+test = ["pytest>=8.0.0"]
+
+[project.scripts]
+xrefkit = "xrefkit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xrefkit*"]
+
+[tool.setuptools.package-data]
+xrefkit = ["resources/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xrefkit-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xrefkit-0.3.0/tests/test_base_sync_ownership.py

@@ -0,0 +1,123 @@
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+
+from xrefkit.ownership import load_ownership
+
+
+def _load_sync_module():
+    module_path = Path(__file__).resolve().parents[1] / "handoff" / "base_sync" / "xrefkit_sync_worklist.py"
+    spec = importlib.util.spec_from_file_location("xrefkit_sync_worklist", module_path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class BaseSyncOwnershipTests(unittest.TestCase):
+    def test_pack_move_classifies_as_moved_in_base(self) -> None:
+        sync = _load_sync_module()
+        local = sync.State()
+        copy = sync.State()
+        head = sync.State()
+        digest = "same-content"
+        local.docs["DOC123456789"] = {
+            "path": "docs/packs/business-intake/entry.md",
+            "hash": digest,
+            "anchors": ["DOC123456789"],
+        }
+        copy.docs["DOC123456789"] = {
+            "path": "docs/packs/business-intake/entry.md",
+            "hash": digest,
+            "anchors": ["DOC123456789"],
+        }
+        head.docs["DOC123456789"] = {
+            "path": "packs/business-intake/pack.md",
+            "hash": digest,
+            "anchors": ["DOC123456789"],
+        }
+
+        items = sync.classify_docs(local, copy, head)
+
+        self.assertEqual("moved_in_base", items[0]["kind"])
+        self.assertEqual("packs/business-intake/pack.md", items[0]["head_path"])
+
+    def test_scan_local_excludes_local_pack_zone(self) -> None:
+        sync = _load_sync_module()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "ownership.yaml").write_text(
+                "zones:\n"
+                "  - id: local-packs\n"
+                "    owner: local\n"
+                "    paths:\n"
+                "      - packs/local/\n"
+                "    catalog: true\n"
+                "    distribution: false\n"
+                "    base_sync: false\n"
+                "    shadowing: true\n"
+                "  - id: shared-packs\n"
+                "    owner: pack\n"
+                "    paths:\n"
+                "      - packs/*/\n"
+                "    catalog: true\n"
+                "    distribution: true\n"
+                "    base_sync: true\n"
+                "    shadowing: true\n",
+                encoding="utf-8",
+            )
+            local_doc = root / "packs" / "local" / "acme" / "knowledge" / "fact.md"
+            local_doc.parent.mkdir(parents=True)
+            local_doc.write_text(
+                "<!-- xid: LOCAL123456 -->\n<a id=\"xid-LOCAL123456\"></a>\n\n# Local\n",
+                encoding="utf-8",
+            )
+            shared_doc = root / "packs" / "shared" / "knowledge" / "fact.md"
+            shared_doc.parent.mkdir(parents=True)
+            shared_doc.write_text(
+                "<!-- xid: SHARED123456 -->\n<a id=\"xid-SHARED123456\"></a>\n\n# Shared\n",
+                encoding="utf-8",
+            )
+
+            ownership = load_ownership(root)
+            state, problems = sync.scan_local(root, ownership)
+
+            self.assertEqual([], problems)
+            self.assertNotIn("LOCAL123456", state.docs)
+            self.assertIn("SHARED123456", state.docs)
+
+    def test_state_from_files_excludes_non_base_sync_zone(self) -> None:
+        sync = _load_sync_module()
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "ownership.yaml").write_text(
+                "zones:\n"
+                "  - id: derived\n"
+                "    owner: generated\n"
+                "    paths:\n"
+                "      - site/\n"
+                "    catalog: false\n"
+                "    distribution: false\n"
+                "    base_sync: false\n"
+                "    shadowing: false\n",
+                encoding="utf-8",
+            )
+            ownership = load_ownership(root)
+            blobs = {
+                "a": {"kind": "plain", "hash": "plain-a"},
+                "b": {"kind": "plain", "hash": "plain-b"},
+            }
+            files = {
+                "site/index.json": "a",
+                "handoff/base_sync/HANDOFF.md": "b",
+            }
+
+            state = sync.state_from_files(files, blobs, ownership)
+
+            self.assertNotIn("site/index.json", state.plain)
+            self.assertEqual("plain-b", state.plain["handoff/base_sync/HANDOFF.md"])
+
+
+if __name__ == "__main__":
+    unittest.main()

xrefkit-0.3.0/tests/test_calibration_lint.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from xrefkit.skillmeta import validate_skill_meta
+
+
+def test_generic_calibration_wording_is_candidate_only_warning(tmp_path: Path) -> None:
+    skill = tmp_path / "skills/sample"
+    skill.mkdir(parents=True)
+    (skill / "meta.md").write_text(
+        """# Skill Meta: sample
+
+- skill_id: `sample`
+- summary: sample
+- use_when: sample task
+- input: input
+- output: output
+- skill_doc: `SKILL.md`
+- maturity: `draft`
+""",
+        encoding="utf-8",
+    )
+    (skill / "SKILL.md").write_text(
+        "# Sample\n\n- Downgrade unsupported conclusions to unknown.\n",
+        encoding="utf-8",
+    )
+
+    result = validate_skill_meta(skill / "meta.md", check_level="draft")
+
+    assert result.ok is True
+    assert any("generic calibration wording candidate" in item for item in result.warnings)
+
+
+def test_skill_template_does_not_embed_generic_calibration_placeholder() -> None:
+    root = Path(__file__).resolve().parents[1]
+    template = (
+        root / "skills/os/skill_flow_authoring/references/skill_body_template.md"
+    ).read_text(encoding="utf-8")
+
+    assert "downgrade unsupported inference" not in template