@drafthq/draft 3.5.3 → 3.7.1

package/scripts/tools/mermaid-from-graph.sh

@@ -45,8 +45,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --diagram) DIAGRAM="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --diagram) DIAGRAM="${2:?--diagram requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -57,9 +57,6 @@ if [[ ! -d "$REPO" ]]; then
     exit 1
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 stub() {
     cat <<'EOF'
 ```mermaid
@@ -71,11 +68,7 @@ EOF
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || stub
-command -v jq >/dev/null 2>&1 || stub
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || stub
+graph_bootstrap "$REPO" || stub
 
 # module-deps: real IMPORTS edges (the auto-derived dependency graph). Self-imports
 # (src == dst) are dropped so the diagram is a true cross-file graph. Capped at 40
@@ -99,7 +92,8 @@ render_co_change() {
 }
 
 render_proto_map() {
-    local res; res="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"routes\"]}" || echo '{}')"
+    local res; res="$(memory_cli get_architecture \
+        "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["routes"]}')" || echo '{}')"
     local edges; edges="$(echo "${res:-{\}}" | jq -r '(.routes // [])[] | "    \"" + ((.method // "")|tostring) + " " + ((.path // "")|tostring) + "\" --> \"" + ((.handler // "?")|tostring) + "\""' 2>/dev/null || true)"
     if [[ -z "$edges" ]]; then return 1; fi
     printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"

package/scripts/tools/migrate-track-frontmatter.sh

@@ -69,15 +69,10 @@ EPHEMERAL_KEYS=(
     "scope_excludes"
 )
 
-# Stable keys that survive in markdown frontmatter.
-STABLE_KEYS=(
-    "project"
-    "module"
-    "track_id"
-    "generated_by"
-    "generated_at"
-    "links"
-)
+# Keys that survive in markdown frontmatter: project, module, track_id,
+# generated_by, generated_at, links. Recorded here for the reader only — the
+# rewrite is driven entirely by EPHEMERAL_KEYS above (a drop-list, not an
+# allow-list), so there is nothing to enumerate in code.
 
 # Strip ephemeral blocks from a markdown file's YAML frontmatter.
 # Approach: read the file; rewrite the frontmatter section so any line whose
@@ -223,7 +218,13 @@ EOF
                 printf 'migrate: would strip ephemeral frontmatter from %s\n' "$path"
             else
                 (( BACKUP )) && cp "$path" "$path.bak"
-                local _tmp; _tmp="$(mktemp "${path}.XXXXXX")"; printf '%s' "$after" > "$_tmp" && mv -f "$_tmp" "$path"
+                # %s\n restores the EOF newline stripped by command substitution
+                # (same pattern as fix-whitespace.sh).
+                local _tmp; _tmp="$(mktemp "${path}.XXXXXX")"
+                printf '%s\n' "$after" > "$_tmp"
+                # mktemp creates 0600 and `mv` swaps the inode — carry the mode across.
+                apply_dest_mode "$_tmp" "$path"
+                mv -f "$_tmp" "$path"
                 printf 'migrate: stripped ephemeral frontmatter from %s\n' "$path"
             fi
         fi

package/scripts/tools/okf-coverage-check.sh

@@ -57,12 +57,12 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --plan) PLAN="$2"; shift 2;;
-        --bundle) BUNDLE="$2"; shift 2;;
-        --min-stub-lines) MIN_STUB_LINES="$2"; shift 2;;
+        --plan) PLAN="${2:?--plan requires a value}"; shift 2;;
+        --bundle) BUNDLE="${2:?--bundle requires a value}"; shift 2;;
+        --min-stub-lines) MIN_STUB_LINES="${2:?--min-stub-lines requires a value}"; shift 2;;
         --no-coverage-page) WRITE_PAGE=0; shift;;
         --json) JSON=1; shift;;
-        --report) REPORT="$2"; shift 2;;
+        --report) REPORT="${2:?--report requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
@@ -90,7 +90,7 @@ DEFERRED=()     # concept_id\treason
 EXPECTED_TOTAL=0; REQUIRED=0
 
 # Iterate expected entries.
-while IFS=$'\t' read -r cid required reason ftype fanin; do
+while IFS=$'\t' read -r cid required reason _ftype fanin; do
     [[ -z "$cid" ]] && continue
     EXPECTED_TOTAL=$((EXPECTED_TOTAL + 1))
     if [[ "$required" == "true" ]]; then
@@ -141,8 +141,8 @@ write_coverage_page() {
         echo ""
         echo "| Component | Wiki page | Status | Fan-in |"
         echo "|-----------|-----------|--------|--------|"
-        local cid status fanin link
-        while IFS=$'\t' read -r cid required reason ftype fanin; do
+        local cid fanin link
+        while IFS=$'\t' read -r cid required reason _ftype fanin; do
             [[ -z "$cid" ]] && continue
             if [[ "$required" == "true" ]]; then
                 if [[ -f "$BUNDLE/$cid" ]]; then
@@ -167,6 +167,7 @@ write_coverage_page() {
             fi
         done < <(jq -r '.expected[] | [.concept_id, (.required|tostring), (.reason_if_deferred // "-"), (.type // "Module"), (.fan_in // 0 | tostring)] | @tsv' "$PLAN")
     } > "$tmp"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
 }
 [[ $WRITE_PAGE -eq 1 ]] && write_coverage_page

package/scripts/tools/okf-emit-catalog.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# okf-emit-catalog.sh — deterministically emit minimum-viable concept pages for
+# every REQUIRED entry in a concept-plan.json that does not yet have a page.
+#
+# Purpose: XL monorepos cannot rely on the LLM to narrate every Module page in
+# one shot. This tool writes quality-gate-passing catalog pages from plan
+# metadata + optional Cargo/README crumbs so init can complete without gaps.
+# Agents may later enrich top-N hotspots; the catalog is the completeness floor.
+#
+# Usage:
+#   okf-emit-catalog.sh --plan FILE --bundle DIR [--repo DIR] [--force]
+#
+# Exit: 0 ok, 1 error, 2 plan/bundle missing.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+PLAN=""
+BUNDLE=""
+REPO="."
+FORCE=0
+
+usage() {
+    cat <<'EOF'
+okf-emit-catalog.sh — write minimum-viable concept pages for missing plan entries.
+
+Usage:
+  okf-emit-catalog.sh --plan FILE --bundle DIR [--repo DIR] [--force]
+
+Flags:
+  --plan FILE    concept-plan.json (required)
+  --bundle DIR   wiki/ bundle directory (required)
+  --repo DIR     repository root for grounding (default: .)
+  --force        Overwrite existing pages (default: skip if present)
+  --help         Show help
+
+Exit: 0 ok, 1 error, 2 missing plan/bundle.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --plan) PLAN="${2:?--plan requires a value}"; shift 2;;
+        --bundle) BUNDLE="${2:?--bundle requires a value}"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --force) FORCE=1; shift;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) echo "Unexpected arg: $1" >&2; exit 1;;
+    esac
+done
+
+[[ -n "$PLAN" && -f "$PLAN" ]] || { echo "ERROR: --plan required" >&2; exit 2; }
+[[ -n "$BUNDLE" && -d "$BUNDLE" ]] || { echo "ERROR: --bundle directory required" >&2; exit 2; }
+[[ -d "$REPO" ]] || { echo "ERROR: --repo is not a directory" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "ERROR: jq required" >&2; exit 1; }
+
+BUNDLE="${BUNDLE%/}"
+REPO="$(cd "$REPO" && pwd)"
+TS="${OKF_CATALOG_TS:-$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "1970-01-01T00:00:00Z")}"
+
+wrote=0
+skipped=0
+
+# Best-effort one-line description from resource path.
+sniff_desc() {
+    local res="$1" lib
+    lib="$REPO/$res/src/lib.rs"
+    [[ -f "$lib" ]] || lib="$REPO/$res/lib.rs"
+    if [[ -f "$lib" ]]; then
+        awk '/^\/\/!/ { sub(/^\/\/![[:space:]]?/, ""); print; exit }' "$lib"
+        return
+    fi
+    if [[ -f "$REPO/$res/README.md" ]]; then
+        awk 'NF && !/^#/ { print; exit }' "$REPO/$res/README.md"
+        return
+    fi
+    printf 'Workspace component at %s.' "$res"
+}
+
+write_page() {
+    local cid="$1" ctype="$2" resource="$3" fan_in="$4"
+    local out="$BUNDLE/$cid"
+    mkdir -p "$(dirname "$out")"
+    if [[ -f "$out" && $FORCE -eq 0 ]]; then
+        skipped=$((skipped+1))
+        return
+    fi
+
+    local title stem section
+    stem="$(basename "$cid" .md)"
+    section="$(dirname "$cid")"
+    title="$stem"
+    local desc
+    desc="$(sniff_desc "$resource")"
+    [[ -n "$desc" ]] || desc="Open when changing the ${stem} component at ${resource}."
+
+    # Routing description (load-bearing for concept map).
+    local routing="Open when changing \`${stem}\` (${resource}). ${desc}"
+    routing="$(printf '%s' "$routing" | tr '\n' ' ' | sed -E 's/[[:space:]]+/ /g' | cut -c1-280)"
+
+    local g1 g2
+    g1="$resource"
+    [[ -e "$REPO/$resource" ]] || g1="README.md"
+    if [[ -f "$REPO/$resource/src/lib.rs" ]]; then
+        g1="$resource/src/lib.rs"
+    elif [[ -f "$REPO/$resource/Cargo.toml" ]]; then
+        g1="$resource/Cargo.toml"
+    elif [[ -f "$REPO/$resource/package.json" ]]; then
+        g1="$resource/package.json"
+    elif [[ -f "$REPO/$resource/go.mod" ]]; then
+        g1="$resource/go.mod"
+    fi
+    g2="README.md"
+    [[ -f "$REPO/README.md" ]] || g2="Cargo.toml"
+    [[ -f "$REPO/$g2" || -f "$REPO/Cargo.toml" ]] || g2="."
+
+    # Types that need mermaid + full sections
+    local needs_diagram=0
+    case "$ctype" in
+        Subsystem|Module|Feature|Entrypoint) needs_diagram=1;;
+    esac
+
+    {
+        echo "---"
+        echo "type: $ctype"
+        echo "title: \"$title\""
+        echo "description: >"
+        echo "  $routing"
+        echo "resource: \"$resource\""
+        echo "tags: [catalog, auto-emitted]"
+        echo "timestamp: \"$TS\""
+        echo "x-grounded-paths: [\"$g1\", \"$g2\"]"
+        echo "x-hotspot-score: 0.0"
+        echo "x-callers: []"
+        echo "x-catalog: true"
+        echo "---"
+        echo ""
+        echo "# $title"
+        echo ""
+        echo "## What it is"
+        echo ""
+        echo "Catalog entry for **\`${stem}\`** at \`${resource}\` (auto-emitted from the concept plan)."
+        echo ""
+        echo "$desc"
+        echo ""
+        echo "Fan-in (plan): ${fan_in}. Enrich this page during deep analysis if it is a hotspot."
+        echo ""
+        if [[ $needs_diagram -eq 1 ]]; then
+            echo "## How it works"
+            echo ""
+            echo "Primary implementation lives under \`${resource}\`. Prefer \`cargo check -p ${stem}\` /"
+            echo "package-local tests when iterating. Full control-flow diagrams belong in a later deep-dive."
+            echo ""
+            echo '```mermaid'
+            echo "flowchart TB"
+            echo "  Consumer[Downstream consumers] --> C[\"${stem}\"]"
+            echo "  C --> Impl[\"${resource}\"]"
+            echo '```'
+            echo ""
+            echo "## Used by"
+            echo ""
+            echo "- Parent wiki indexes under \`${section}/\`"
+            echo "- Workspace members that depend on \`${stem}\` (see package manifest)"
+            echo ""
+            echo "## Blast radius"
+            echo ""
+            echo "Changes to public APIs in \`${resource}\` may break dependent packages in this monorepo."
+            echo "Run targeted tests for \`${stem}\` and re-check direct reverse dependents."
+            echo ""
+            echo "## See also"
+            echo ""
+            echo "- [section index](index.md)"
+            echo "- Repository README / architecture overview"
+            echo ""
+            echo "## Notes"
+            echo ""
+            echo "- Emitted by \`okf-emit-catalog.sh\` so completeness does not depend on LLM coverage."
+            echo "- Safe to overwrite with a richer concept page on refresh/deep-dive (\`--force\`)."
+        else
+            echo "## How it works"
+            echo ""
+            echo "See \`${resource}\` and related package docs."
+            echo ""
+            echo "## See also"
+            echo ""
+            echo "- [section index](index.md)"
+        fi
+    } > "$out"
+    wrote=$((wrote+1))
+}
+
+while IFS=$'\t' read -r cid ctype resource fan_in required; do
+    [[ -z "$cid" ]] && continue
+    [[ "$required" == "true" ]] || continue
+    write_page "$cid" "${ctype:-Module}" "${resource:-.}" "${fan_in:-0}"
+done < <(jq -r '.expected[] | [.concept_id, (.type // "Module"), (.resource // "."), ((.fan_in // 0)|tostring), (.required|tostring)] | @tsv' "$PLAN")
+
+# Ensure section index stubs exist so render/section-indexes can run.
+for sec in overview systems features reference entrypoints; do
+    dir="$BUNDLE/$sec"
+    [[ -d "$dir" ]] || continue
+    if [[ ! -f "$dir/index.md" ]]; then
+        cat > "$dir/index.md" <<EOF
+---
+title: "$sec"
+---
+
+# $sec
+
+## Concept Map
+
+<!-- CONCEPT-MAP:START -->
+<!-- CONCEPT-MAP:END -->
+EOF
+    fi
+done
+
+# Bundle root index if missing — only link section dirs that exist (no dangling rows).
+if [[ ! -f "$BUNDLE/index.md" ]]; then
+    {
+        echo "---"
+        echo "type: Subsystem"
+        echo "title: Project Wiki"
+        echo "description: >"
+        echo "  Root index of the project wiki. Start here, then route via the Concept Map."
+        echo "resource: ."
+        echo "tags: [index]"
+        echo "timestamp: \"$TS\""
+        echo "okf_version: \"0.1\""
+        echo "okf_types_version: \"0.1\""
+        echo "---"
+        echo ""
+        echo "# Project Wiki"
+        echo ""
+        echo "## Sections"
+        echo ""
+        echo "| Section | Index |"
+        echo "|---------|-------|"
+        for sec in overview systems features reference entrypoints; do
+            if [[ -d "$BUNDLE/$sec" && -f "$BUNDLE/$sec/index.md" ]]; then
+                echo "| $sec | [$sec/index.md]($sec/index.md) |"
+            fi
+        done
+        echo ""
+        echo "## Concept Map"
+        echo ""
+        echo "<!-- CONCEPT-MAP:START -->"
+        echo "<!-- CONCEPT-MAP:END -->"
+    } > "$BUNDLE/index.md"
+fi
+
+echo "okf-emit-catalog: wrote=$wrote skipped_existing=$skipped plan=$PLAN bundle=$BUNDLE"
+exit 0

package/scripts/tools/okf-fix-links.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# okf-fix-links.sh — rewrite and validate markdown links in draft/ views.
+#
+# Fixes the class of bugs seen when okf-render-views concatenates wiki pages into
+# draft/architecture.md (sibling-relative links and ambiguous basenames break).
+# Also validates the whole draft/ tree (or a single file).
+#
+# Usage:
+#   okf-fix-links.sh --draft DIR [--fix] [--check]
+#   okf-fix-links.sh --file FILE --wiki DIR [--fix]
+#
+# Exit: 0 all links resolve (after optional fix), 1 broken links remain, 2 usage.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+DRAFT=""
+FILE=""
+WIKI=""
+DO_FIX=0
+
+usage() {
+    cat <<'EOF'
+okf-fix-links.sh — fix/validate markdown links in Draft OKF outputs.
+
+Usage:
+  okf-fix-links.sh --draft DIR [--fix] [--check]
+  okf-fix-links.sh --file architecture.md --wiki DIR/wiki [--fix]
+
+Flags:
+  --draft DIR   draft/ directory (architecture.md + wiki/ + .ai-context.md)
+  --file FILE   single markdown file to rewrite/check
+  --wiki DIR    wiki bundle (required with --file for basename map)
+  --fix        rewrite broken/ambiguous links in place
+  --check       accepted for symmetry with --fix; checking is unconditional
+  --help
+
+Exit: 0 clean, 1 broken links remain, 2 bad invocation.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --draft) DRAFT="${2:?--draft requires a value}"; shift 2;;
+        --file) FILE="${2:?--file requires a value}"; shift 2;;
+        --wiki) WIKI="${2:?--wiki requires a value}"; shift 2;;
+        --fix) DO_FIX=1; shift;;
+        --check) shift;;   # checking always runs; accepted so callers can be explicit
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 2;;
+        *) echo "Unexpected arg: $1" >&2; exit 2;;
+    esac
+done
+
+if [[ -n "$DRAFT" ]]; then
+    DRAFT="${DRAFT%/}"
+    [[ -d "$DRAFT" ]] || { echo "ERROR: --draft not a directory" >&2; exit 2; }
+    WIKI="${WIKI:-$DRAFT/wiki}"
+    FILE="${FILE:-$DRAFT/architecture.md}"
+fi
+
+[[ -n "$FILE" && -f "$FILE" ]] || { echo "ERROR: --file or --draft/architecture.md required" >&2; exit 2; }
+[[ -n "$WIKI" && -d "$WIKI" ]] || { echo "ERROR: wiki dir required" >&2; exit 2; }
+
+command -v python3 >/dev/null 2>&1 || {
+    echo "ERROR: python3 is required by ${0##*/} (link rewriting and validation)" >&2
+    exit 2
+}
+
+# Link resolution (basename disambiguation, section preference) lives in the
+# Python pass inside fix_file — it builds its own basename map from the same
+# wiki tree. The former bash twin, pick_target(), had no callers.
+
+# Anchor and link validation lives in the Python pass at the bottom of this
+# file — it is the only checker, and it computes its own slug table.
+
+fix_file() {
+    local src="$1"
+    local tmp; tmp="$(mktemp)"
+    python3 - "$src" "$WIKI" "$tmp" <<'PY'
+import sys, re
+from pathlib import Path
+
+src = Path(sys.argv[1])
+wiki = Path(sys.argv[2])
+out = Path(sys.argv[3])
+text = src.read_text(encoding="utf-8", errors="replace")
+
+# basename -> [wiki-relative draft paths]
+bmap = {}
+for p in wiki.rglob("*.md"):
+    rel = "wiki/" + str(p.relative_to(wiki)).replace("\\", "/")
+    bmap.setdefault(p.name, []).append(rel)
+
+def pick(base, label):
+    cands = bmap.get(base, [])
+    if not cands:
+        return None
+    if len(cands) == 1:
+        return cands[0]
+    lab = label.lower()
+    def prefer(substr):
+        for c in cands:
+            if substr in c:
+                return c
+        return None
+    if any(k in lab for k in ("product", "feature", "user guide", "install", "onboarding")):
+        p = prefer("/features/")
+        if p: return p
+    if any(k in lab for k in ("build", "runbook", "ops", "source", "cargo")):
+        p = prefer("/overview/")
+        if p: return p
+    for s in ("/systems/", "/features/", "/overview/", "/reference/", "/entrypoints/"):
+        p = prefer(s)
+        if p: return p
+    return cands[0]
+
+def gfm_slug(heading: str) -> str:
+    s = heading.strip().lower()
+    s = re.sub(r"[^\w\s-]", "", s, flags=re.UNICODE)
+    s = re.sub(r"\s+", "-", s)
+    s = re.sub(r"-+", "-", s).strip("-")
+    return s
+
+# heading map for anchor fix
+slug_counts = {}
+heading_by_text = {}
+for line in text.splitlines():
+    m = re.match(r"^(#{1,6})\s+(.+)$", line)
+    if not m:
+        continue
+    raw = m.group(2).strip()
+    base = gfm_slug(raw)
+    n = slug_counts.get(base, 0)
+    slug_counts[base] = n + 1
+    slug = base if n == 0 else f"{base}-{n}"
+    heading_by_text[raw] = slug
+
+def repl(m):
+    label, href = m.group(1), m.group(2).strip()
+    # strip rustdoc
+    if "::" in href and not href.startswith(("http", "wiki/", "#", "../", "./")):
+        return f"`{label}`"
+    if href.startswith(("http://", "https://", "mailto:")):
+        return m.group(0)
+    if href.startswith("#"):
+        if label in heading_by_text and href[1:] != heading_by_text[label]:
+            return f"[{label}](#{heading_by_text[label]})"
+        g = gfm_slug(label)
+        # unique match on gfm of heading texts
+        for raw, slug in heading_by_text.items():
+            if gfm_slug(raw) == g and href[1:] != slug:
+                return f"[{label}](#{slug})"
+        return m.group(0)
+    path, sep, frag = href.partition("#")
+    frag_s = ("#" + frag) if frag else ""
+    if path.startswith("wiki/"):
+        return m.group(0)
+    m2 = re.match(r"^\.\./((?:systems|features|overview|entrypoints|reference)/.+)$", path)
+    if m2:
+        return f"[{label}](wiki/{m2.group(1)}{frag_s})"
+    if re.match(r"^(systems|features|overview|entrypoints|reference)/", path):
+        return f"[{label}](wiki/{path}{frag_s})"
+    if path.endswith(".md") and "/" not in path:
+        picked = pick(path, label)
+        if picked:
+            return f"[{label}]({picked}{frag_s})"
+    return m.group(0)
+
+new = re.sub(r"\[([^\]]*)\]\(([^)]+)\)", repl, text)
+out.write_text(new if new.endswith("\n") else new + "\n", encoding="utf-8")
+PY
+    apply_dest_mode "$tmp" "$src"   # mktemp is 0600; mv would strip the dest's mode
+    mv "$tmp" "$src"
+}
+
+if [[ $DO_FIX -eq 1 ]]; then
+    fix_file "$FILE"
+    # Also fix .ai-context when draft mode
+    if [[ -n "$DRAFT" && -f "$DRAFT/.ai-context.md" ]]; then
+        fix_file "$DRAFT/.ai-context.md"
+    fi
+fi
+
+# Check — the single source of link/anchor truth
+broken_out="$(python3 - "$FILE" "${DRAFT:-$(dirname "$FILE")}" "$WIKI" <<'PY'
+import sys, re
+from pathlib import Path
+src = Path(sys.argv[1])
+draft = Path(sys.argv[2])
+wiki = Path(sys.argv[3])
+text = src.read_text(encoding="utf-8", errors="replace")
+
+def gfm_slug(heading: str) -> str:
+    s = heading.strip().lower()
+    s = re.sub(r"[^\w\s-]", "", s, flags=re.UNICODE)
+    s = re.sub(r"\s+", "-", s)
+    s = re.sub(r"-+", "-", s).strip("-")
+    return s
+
+slug_counts = {}
+slugs = set()
+for line in text.splitlines():
+    m = re.match(r"^(#{1,6})\s+(.+)$", line)
+    if not m: continue
+    base = gfm_slug(m.group(2))
+    n = slug_counts.get(base, 0)
+    slug_counts[base] = n + 1
+    slugs.add(base if n == 0 else f"{base}-{n}")
+
+broken = []
+ok = 0
+for m in re.finditer(r"\[([^\]]*)\]\(([^)]+)\)", text):
+    label, href = m.group(1), m.group(2).strip()
+    if href.startswith(("http://","https://","mailto:")):
+        ok += 1; continue
+    if href.startswith("#"):
+        if href[1:] in slugs:
+            ok += 1
+        else:
+            broken.append(f"anchor {href} ({label[:40]})")
+        continue
+    path = href.split("#",1)[0]
+    if not path:
+        ok += 1; continue
+    # Resolve only against the two bases a link inside this document can mean:
+    # the document's own directory and the draft/ root. Never against the
+    # process CWD — a same-named file in the caller's cwd used to make a
+    # genuinely dangling link report clean (exit flipped 1 -> 0).
+    cands = [src.parent/path, draft/path]
+    if any(c.exists() for c in cands):
+        ok += 1
+    else:
+        broken.append(f"file {href} ({label[:40]})")
+print(f"OK={ok}")
+print(f"BROKEN={len(broken)}")
+for b in broken[:50]:
+    print(b)
+PY
+)"
+
+echo "$broken_out"
+bcount="$(echo "$broken_out" | sed -n 's/^BROKEN=//p' | head -1)"
+if [[ "${bcount:-1}" != "0" ]]; then
+    echo "okf-fix-links: FAILED ($bcount broken in $FILE)" >&2
+    exit 1
+fi
+echo "okf-fix-links: clean ($FILE)"
+exit 0