fix(skill): resolve references/ wikilinks whose stem contains a dot (#120)

* fix(skill): resolve references/ wikilinks whose stem contains a dot

`validate_skill` appended the implicit `.md` to a `[[references/...]]` link
only when `Path(link).suffix` was empty. `Path.suffix` returns everything
after the last dot, so a reference whose stem contains a dot — e.g.
`[[references/api.v2]]` or `[[references/v1.2-guide]]` — has a truthy suffix
(`.v2` / `.2-guide`). The `.md` was therefore never appended and the
validator looked for an extension-less `references/api.v2`, emitting a false
"doesn't exist" error even though `references/api.v2.md` is present and
correctly linked. (`WIKILINK_RE` allows `.` in the target, so such links are
legal and reach this branch.)

Append `.md` based on a literal `.md` check instead of `Path.suffix`, so a
dotted stem is suffixed correctly while an explicit `...md` link is left
alone. Genuinely missing references still error.

Adds a regression test for the dotted-stem case (the existing
`test_wikilink_without_md_suffix_resolves` only covered a dot-free stem).

* skill: reject references/ wikilinks that escape the references directory

Review feedback: WIKILINK_RE allows '.' and '/', so '[[references/../SKILL]]'
resolved outside references/ and was accepted whenever the resolved file
existed (and would crash the not-found message's relative_to(skill_dir)).
Reject any link whose resolved target is not under references/.

Author: jichaowang02-lang

openkb/skill/validator.py

@@ -207,10 +207,20 @@ def validate_skill(skill_dir: Path, *, strict: bool = False) -> ValidationResult
     # references/ wikilink resolution
     wikilinks = WIKILINK_RE.findall(text)
     for link in wikilinks:
-        # link may or may not include .md suffix
-        target = refs_dir / link
-        if not target.suffix:
-            target = target.with_suffix(".md")
+        # The link may already include the .md suffix; append it otherwise.
+        # Test the literal ".md" rather than Path.suffix — a dotted stem like
+        # "api.v2" has a truthy suffix (".v2"), so Path.suffix would skip the
+        # ".md" and then look for a non-existent extension-less file.
+        target = refs_dir / (link if link.lower().endswith(".md") else f"{link}.md")
+        # A reference must resolve to a file *under* references/ — reject any
+        # that escape it (e.g. "[[references/../SKILL]]"), which would also
+        # break the relative_to(skill_dir) call in the not-found message below.
+        if not target.resolve().is_relative_to(refs_dir.resolve()):
+            result.errors.append(
+                f"SKILL.md references [[references/{link}]] which resolves "
+                f"outside the references/ directory."
+            )
+            continue
         if not target.exists():
             result.errors.append(
                 f"SKILL.md references [[references/{link}]] but "

tests/test_skill_validator.py

@@ -259,6 +259,32 @@ def test_wikilink_without_md_suffix_resolves(tmp_path):
     assert result.passed, result.errors
 
 
+def test_wikilink_dotted_stem_without_md_suffix_resolves(tmp_path):
+    # A reference name whose stem contains a dot (e.g. "api.v2") must still get
+    # the implicit ".md". Path.suffix would treat ".v2" as the suffix and skip
+    # appending ".md", falsely reporting the existing api.v2.md as missing.
+    sd = _write_skill(
+        tmp_path, "ref-dotted-stem",
+        body="See [[references/api.v2]] for details.\n",
+        refs={"api.v2.md": "# api v2\n"},
+    )
+    result = validate_skill(sd)
+    assert result.passed, result.errors
+
+
+def test_wikilink_escaping_references_dir_is_rejected(tmp_path):
+    # A link that resolves outside references/ (e.g. "../SKILL") must error —
+    # not be accepted just because the resolved target (here SKILL.md) exists.
+    sd = _write_skill(
+        tmp_path, "ref-escape",
+        body="See [[references/../SKILL]] for details.\n",
+        refs={"topic.md": "# topic\n"},
+    )
+    result = validate_skill(sd)
+    assert not result.passed
+    assert any("outside the references/" in e for e in result.errors)
+
+
 # ---------------------------------------------------------------------------
 # scripts/ imports — strict mode only
 # ---------------------------------------------------------------------------