fix(governance): validate shortcut references before colons

.agents/skills/docs-governance/scripts/markdown_links.py

@@ -139,14 +139,20 @@ def normalize_reference_label(label: str) -> str:
 
 
 def reference_link_targets(text: str) -> list[str]:
+    definition_matches = list(REFERENCE_DEFINITION_RE.finditer(text))
     definitions = {
         normalize_reference_label(match.group("label")): match.group("target")
-        for match in REFERENCE_DEFINITION_RE.finditer(text)
+        for match in definition_matches
     }
     targets: list[str] = []
     for match in REFERENCE_USAGE_RE.finditer(text):
+        if any(
+            definition.start() <= match.start() < definition.end()
+            for definition in definition_matches
+        ):
+            continue
         following = text[match.end() : match.end() + 1]
-        if following in {"(", ":"}:
+        if following == "(":
             continue
         label = match.group("label")
         key = normalize_reference_label(label or match.group("text"))

skills/docs-governance/scripts/markdown_links.py

@@ -139,14 +139,20 @@ def normalize_reference_label(label: str) -> str:
 
 
 def reference_link_targets(text: str) -> list[str]:
+    definition_matches = list(REFERENCE_DEFINITION_RE.finditer(text))
     definitions = {
         normalize_reference_label(match.group("label")): match.group("target")
-        for match in REFERENCE_DEFINITION_RE.finditer(text)
+        for match in definition_matches
     }
     targets: list[str] = []
     for match in REFERENCE_USAGE_RE.finditer(text):
+        if any(
+            definition.start() <= match.start() < definition.end()
+            for definition in definition_matches
+        ):
+            continue
         following = text[match.end() : match.end() + 1]
-        if following in {"(", ":"}:
+        if following == "(":
             continue
         label = match.group("label")
         key = normalize_reference_label(label or match.group("text"))

tests/test_docs_governance_audit.py

@@ -309,6 +309,17 @@ def test_artifact_scope_checks_reference_style_markdown_links(
     assert "missing-guide.md" in result.stdout
 
 
+def test_artifact_scope_checks_shortcut_reference_followed_by_colon(
+    project: Path,
+) -> None:
+    (project / "index.md").write_text(
+        "See [docs]: details\n\n[docs]: missing-guide.md\n", encoding="utf-8"
+    )
+    result = run_audit(project, "artifacts")
+    assert result.returncode == 1
+    assert "Broken Markdown link: 'index.md' -> 'missing-guide.md'" in result.stdout
+
+
 @pytest.mark.parametrize("target_line", ("  missing-guide.md", "missing-guide.md"))
 def test_artifact_scope_checks_continuation_line_reference_target(
     project: Path, target_line: str