link-verification

link-verification

Hard gate for internal wiki, repo, and external URLs. AI models hallucinate URLs. Verify before write. Wrong skill? Issue tickets → issue-link-verification · Wiki claims → wiki-verify.

When to Use

• Before writing any wiki page that contains URLs, repo links, or issue references
• When asked to "verify links", "check broken links", or "fix wiki links"
• Triggered by: verify links, check this link, wiki:verify-links, link:verify
• Wrong skill? Issue ticket links → issue-link-verification · Claim accuracy → wiki-verify

Gate (exit 0 ok · 1 block · 2 warn-only)

Type	Example	On failure
Internal wiki	/doc/slug-xyz123	HARD BLOCK (404)
Repo	https://github.com/{org}/{repo}	HARD BLOCK (often hallucinated)
Issue ref	#1234, ORG-42	WARN (may be private)
External	https://example.com	WARN (transient downtime)

Exit 1 → orchestrator MUST halt publish; exit 2 → publish with user ack.

Procedure

1 — Extract links

{ grep -nE '\[[^]]+\]\([^)]+\)' draft.md
  grep -nEo 'https?://[^[:space:]<>()]+' draft.md; } > links.txt

2 — Verify each link (exit-code contract)

block=0; warn=0
while IFS= read -r line; do
  url=$(echo "$line" | sed -E 's/.*\(([^)]+)\).*/\1/; s/.*: //')
  case "$url" in
    /doc/*)
      tools/wiki-read.sh get "${url#/doc/}" > /dev/null 2>&1 \
        && echo "PASS  wiki  $url" \
        || { echo "FAIL  wiki  $url"; block=1; } ;;
    https://github.com/*)
      repo=$(echo "$url" | sed -E 's#https://github\.com/([^/]+/[^/]+).*#\1#')
      gh api "repos/$repo" > /dev/null 2>&1 \
        && echo "PASS  repo  $url" \
        || { echo "FAIL  repo  $url"; block=1; } ;;
    http*://*)
      code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 8 "$url")
      [ "$code" = 200 ] && echo "PASS  ext   $url" \
        || { echo "WARN  ext   $url (HTTP $code)"; warn=1; } ;;
  esac
done < links.txt
exit $(( block ? 1 : (warn ? 2 : 0) ))

3 — On FAIL (wiki or repo)

1. tools/wiki-read.sh search "<keywords>" (wiki) or gh search repos "<name>" (GitHub)
2. Replace the link in the draft with the verified URL
3. Re-run Step 2. Do NOT publish until exit 0 or 2.

Hallucination patterns to never trust blind

Pattern	Why wrong
github.com/{assumed-org}/{repo}	Model assumes GitHub is universal
File links with line numbers	File structure changes
main branch	May be master or other
/doc/made-up-slug	Wiki slug fabricated without API check

Failure modes

Failure	Fix
200 but content doesn't match	Read target title; confirm anchor match
Wiki slug valid but wrong page	Compare wiki-read.sh get title against anchor
Timeout → WARN by default	Retry once; then mark FAIL not WARN
Only checked wiki, skipped external	Run Step 2 for ALL types every time

Background, incident log, and code-references template: see references/code-references-template.md if present.

Companions: wiki-orchestrator · wiki-verify · wiki-content-coherence · wiki-debunker · issue-link-verification · verification-before-completion