@drafthq/draft 3.6.0 → 3.7.2

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

@@ -20,7 +20,6 @@ DRAFT=""
 FILE=""
 WIKI=""
 DO_FIX=0
-DO_CHECK=1
 
 usage() {
     cat <<'EOF'
@@ -35,7 +34,7 @@ Flags:
   --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       report broken links (default on)
+  --check       accepted for symmetry with --fix; checking is unconditional
   --help
 
 Exit: 0 clean, 1 broken links remain, 2 bad invocation.
@@ -48,7 +47,7 @@ while [[ $# -gt 0 ]]; do
         --file) FILE="${2:?--file requires a value}"; shift 2;;
         --wiki) WIKI="${2:?--wiki requires a value}"; shift 2;;
         --fix) DO_FIX=1; shift;;
-        --check) DO_CHECK=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;;
@@ -65,83 +64,17 @@ 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; }
 
-# Build basename → list of wiki-relative paths (relative to draft root as wiki/...)
-declare -A BASENAME_MAP_MULTI=()
-while IFS= read -r -d '' p; do
-    rel="wiki/${p#"$WIKI"/}"
-    base="$(basename "$p")"
-    if [[ -n "${BASENAME_MAP_MULTI[$base]:-}" ]]; then
-        BASENAME_MAP_MULTI[$base]="${BASENAME_MAP_MULTI[$base]}|$rel"
-    else
-        BASENAME_MAP_MULTI[$base]="$rel"
-    fi
-done < <(find "$WIKI" -type f -name '*.md' -print0)
-
-pick_target() {
-    local base="$1" label="$2"
-    local cands="${BASENAME_MAP_MULTI[$base]:-}"
-    [[ -n "$cands" ]] || { echo ""; return; }
-    if [[ "$cands" != *"|"* ]]; then
-        printf '%s' "$cands"
-        return
-    fi
-    local lab; lab="$(printf '%s' "$label" | tr '[:upper:]' '[:lower:]')"
-    IFS='|' read -ra arr <<< "$cands"
-    local pref
-    if [[ "$lab" == *product* || "$lab" == *feature* || "$lab" == *user*guide* || "$lab" == *install* ]]; then
-        for pref in "${arr[@]}"; do [[ "$pref" == *"/features/"* ]] && { printf '%s' "$pref"; return; }; done
-    fi
-    if [[ "$lab" == *build* || "$lab" == *runbook* || "$lab" == *ops* || "$lab" == *source* ]]; then
-        for pref in "${arr[@]}"; do [[ "$pref" == *"/overview/"* ]] && { printf '%s' "$pref"; return; }; done
-    fi
-    for order in /systems/ /features/ /overview/ /reference/ /entrypoints/; do
-        for pref in "${arr[@]}"; do
-            [[ "$pref" == *"$order"* ]] && { printf '%s' "$pref"; return; }
-        done
-    done
-    printf '%s' "${arr[0]}"
+command -v python3 >/dev/null 2>&1 || {
+    echo "ERROR: python3 is required by ${0##*/} (link rewriting and validation)" >&2
+    exit 2
 }
 
-# Collect heading slugs from a file for anchor checks
-build_slugs() {
-    local f="$1"
-    declare -gA SLUGS=()
-    local counts=()
-    # shellcheck disable=SC2034
-    while IFS= read -r line; do
-        [[ "$line" =~ ^#{1,6}[[:space:]]+(.*)$ ]] || continue
-        local raw="${BASH_REMATCH[1]}"
-        local s; s="$(gfm_slug "$raw")"
-        local n="${SLUGS[_count_$s]:-0}"
-        SLUGS[_count_$s]=$((n+1))
-        if [[ $n -eq 0 ]]; then
-            SLUGS[$s]=1
-        else
-            SLUGS["${s}-$n"]=1
-        fi
-    done < "$f"
-}
+# 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.
 
-resolve_ok() {
-    local src="$1" href="$2"
-    [[ "$href" =~ ^https?:// || "$href" =~ ^mailto: ]] && return 0
-    if [[ "$href" == \#* ]]; then
-        local a="${href#\#}"
-        [[ -n "${SLUGS[$a]:-}" ]] && return 0
-        return 1
-    fi
-    local path="${href%%\#*}"
-    [[ -z "$path" ]] && return 0
-    local dir; dir="$(cd "$(dirname "$src")" && pwd)"
-    local draft_root=""
-    if [[ -n "$DRAFT" ]]; then
-        draft_root="$(cd "$DRAFT" && pwd)"
-    else
-        draft_root="$(cd "$(dirname "$src")" && pwd)"
-    fi
-    [[ -e "$dir/$path" || -e "$draft_root/$path" || -e "$path" ]] && return 0
-    return 1
-}
+# 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"
@@ -239,11 +172,8 @@ def repl(m):
 new = re.sub(r"\[([^\]]*)\]\(([^)]+)\)", repl, text)
 out.write_text(new if new.endswith("\n") else new + "\n", encoding="utf-8")
 PY
-    if [[ $DO_FIX -eq 1 ]]; then
-        mv "$tmp" "$src"
-    else
-        rm -f "$tmp"
-    fi
+    apply_dest_mode "$tmp" "$src"   # mktemp is 0600; mv would strip the dest's mode
+    mv "$tmp" "$src"
 }
 
 if [[ $DO_FIX -eq 1 ]]; then
@@ -254,16 +184,7 @@ if [[ $DO_FIX -eq 1 ]]; then
     fi
 fi
 
-# Check
-build_slugs "$FILE"
-broken=0
-total=0
-while IFS= read -r line; do
-    # crude extract — enough for validation
-    :
-done < /dev/null
-
-# Python check for reliability
+# Check — the single source of link/anchor truth
 broken_out="$(python3 - "$FILE" "${DRAFT:-$(dirname "$FILE")}" "$WIKI" <<'PY'
 import sys, re
 from pathlib import Path
@@ -304,7 +225,11 @@ for m in re.finditer(r"\[([^\]]*)\]\(([^)]+)\)", text):
     path = href.split("#",1)[0]
     if not path:
         ok += 1; continue
-    cands = [src.parent/path, draft/path, Path(path)]
+    # 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:

package/scripts/tools/okf-plan-concepts.sh

@@ -175,7 +175,7 @@ plan_from_cargo_workspace() {
     [[ -f "$cargo" ]] || return 1
     # Only treat as workspace if [workspace] present with members.
     grep -qE '^\[workspace\]' "$cargo" || return 1
-    grep -qE 'members\s*=' "$cargo" || return 1
+    grep -qE 'members[[:space:]]*=' "$cargo" || return 1
 
     local members=()
     # Extract quoted paths inside the members = [ ... ] array (possibly multi-line).
@@ -424,13 +424,10 @@ else
     plan_from_cargo_workspace || true
     plan_from_npm_workspaces || true
     plan_from_go_modules || true
-    if plan_from_graph; then
-        :
-    elif [[ ${#E_ID[@]} -eq 0 ]]; then
-        plan_from_heuristic
-        DISCOVERY_META+=("heuristic")
-    fi
-    # If graph failed but we have cargo/npm/go, still success.
+    plan_from_graph || true
+    # Last resort only: any of cargo/npm/go/graph succeeding leaves E_ID non-empty
+    # and skips this. Re-running the heuristic a second time can never add what
+    # the first pass didn't find, so there is one call site, not two.
     if [[ ${#E_ID[@]} -eq 0 ]]; then
         plan_from_heuristic
         DISCOVERY_META+=("heuristic")

package/scripts/tools/okf-render-views.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # okf-render-views.sh — render the demoted views from an OKF taxonomy bundle.
 #
-# The wiki/ bundle is the source of truth. This produces the two derived,
+# The wiki/ bundle is the source of truth. This produces the derived,
 # human-facing views deterministically (so they never drift from the bundle and
 # carry zero extra maintenance):
 #   1. architecture.md  — a single linear concatenation of every concept page,
@@ -24,6 +24,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=scripts/tools/_lib.sh
 source "$SCRIPT_DIR/_lib.sh"
 
+command -v python3 >/dev/null 2>&1 || {
+    echo "ERROR: python3 is required by ${0##*/} (link rewriting in rendered views)" >&2
+    exit 2
+}
+
 BUNDLE=""
 ARCH_OUT=""
 WEB_OUT=""
@@ -56,7 +61,7 @@ Flags:
                            this tool has no clock dependency).
   --help                   Show this help.
 
-Requires jq (already a Draft prereq) for --web. Exit 0 ok, 1 error, 2 bundle not found.
+Requires jq (for --web) and python3 (link rewriting). Exit 0 ok, 1 error, 2 bundle not found.
 EOF
 }
 
@@ -100,8 +105,6 @@ ordered_pages() {
     done
 }
 
-# Strip YAML frontmatter from a page (leading --- ... --- block on line 1).
-
 # Rewrite markdown links so concatenated architecture.md (at draft/) resolves them.
 # stdin body; $1 = bundle-relative path e.g. systems/foo.md
 rewrite_body_links() {
@@ -133,6 +136,7 @@ sys.stdout.write(re.sub(r"\[([^\]]*)\]\(([^)]+)\)", repl, text))
 ' "$sec"
 }
 
+# Strip YAML frontmatter from a page (leading --- ... --- block on line 1).
 strip_frontmatter() {
     awk '
         NR==1 && /^---$/ { fm=1; next }
@@ -217,6 +221,7 @@ render_architecture() {
             strip_frontmatter "$BUNDLE/$rel" | rewrite_body_links "$rel"
         done < <(ordered_pages)
     } >"$tmp"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
     if [[ -x "$SCRIPT_DIR/okf-fix-links.sh" ]]; then
         draft_dir="$(cd "$(dirname "$out")" && pwd)"
@@ -243,12 +248,7 @@ build_concept_map() {
         [[ -n "$type" ]] || continue
         title="$(get_yaml_field "$page" title)"
         [[ -n "$title" ]] || title="$rel"
-        # description may be a folded (>) block — take the first non-empty body line.
-        desc="$(awk '
-            NR==1&&/^---$/{fm=1;next} fm&&/^---$/{exit}
-            fm && /^description:/ { collect=1; sub(/^description:[[:space:]]*>?[[:space:]]*/,""); if($0!=""){print; exit} next }
-            fm && collect { sub(/^[[:space:]]+/,""); if($0!=""){print; exit} }
-        ' "$page")"
+        desc="$(page_desc "$page")"
         echo "| [${title}](${rel}) | ${type} | ${desc} |"
     done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 }
@@ -313,14 +313,18 @@ inject_concept_map() {
         /<!-- CONCEPT-MAP:END -->/ { skip=0 }
         !skip { print }
     ' "$target" >"$tmp"
+    apply_dest_mode "$tmp" "$target"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$target"
     echo "injected Concept Map → $target"
 }
 
 # --- 3. Render a self-contained offline HTML viewer (single file) ---
 # All pages are inlined as JSON; a small built-in markdown renderer draws them in
-# the browser. No server, no internet, no CDN. jq encodes page content safely
-# (and we neutralize any literal </ so embedded "</script>" can't break parsing).
+# the browser. No server, no internet, no CDN. jq encodes page content safely,
+# and the whole emitted data block is passed through a `</` → `<\/` filter: JSON
+# escaping does NOT stop a literal "</script>" from closing the <script> element,
+# and page titles/types/paths come from repo-derived frontmatter, so every field
+# has to be neutralized, not just the markdown body.
 render_web() {
     local out="$1"
     command -v jq >/dev/null 2>&1 || { echo "ERROR: --web requires jq" >&2; return 1; }
@@ -388,14 +392,14 @@ HTML_HEAD
                 "$(jq -Rn --arg v "$rel" '$v')" \
                 "$(jq -Rn --arg v "$title" '$v')" \
                 "$(jq -Rn --arg v "$type" '$v')" \
-                "$(strip_frontmatter "$page" | jq -Rs . | sed 's#</#<\\/#g')"
+                "$(strip_frontmatter "$page" | jq -Rs .)"
         done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
         echo "};"
         # ORDER: bundle root index.md first, then everything else sorted.
         echo "const ORDER = Object.keys(PAGES).sort(function(a,b){"
         echo "  if(a==='index.md') return -1; if(b==='index.md') return 1;"
         echo "  return a<b?-1:a>b?1:0; });"
-    } >>"$tmp"
+    } | sed 's#</#<\\/#g' >>"$tmp"
 
     cat >>"$tmp" <<'HTML_TAIL'
 function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
@@ -487,6 +491,7 @@ show(decodeURIComponent(location.hash.slice(1)) || ORDER[0]);
 HTML_TAIL
 
     mkdir -p "$(dirname "$out")"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
     echo "rendered offline HTML viewer → $out ($(find "$BUNDLE" -type f -name '*.md' | grep -c .) pages)"
 }

package/scripts/tools/okf-validate-quality.sh

@@ -73,6 +73,17 @@ body_of() {
     awk 'NR==1&&/^---$/{fm=1;next} fm&&/^---$/{fm=0;next} !fm{print}' "$1"
 }
 
+# Body text the Q-TEMPLATE scan is allowed to see: fenced code blocks and
+# shell-style ${VAR} expansions removed. Both legitimately carry {ALL_CAPS}
+# spans that are not unreplaced placeholders (a page quoting `${HOME}` or a CI
+# snippet would otherwise fail).
+template_scan_body() {
+    body_of "$1" | awk '
+        /^[[:space:]]*```/ { fence = !fence; next }
+        !fence { gsub(/\$\{[A-Za-z_][A-Za-z0-9_]*\}/, ""); print }
+    '
+}
+
 # Count body lines after the frontmatter close (Q-LEN = "lines after frontmatter").
 body_lines() { body_of "$1" | wc -l | tr -d ' '; }
 
@@ -114,7 +125,7 @@ mermaid_lint() {
         echo "unicode arrow in mermaid (use --> not →)"; return 1
     fi
     # '&' node chaining (common breaker).
-    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_]\s*&\s*[A-Za-z0-9_]'; then
+    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_][[:space:]]*&[[:space:]]*[A-Za-z0-9_]'; then
         echo "'&' node chaining in mermaid"; return 1
     fi
     # Reserved bareword node ids.
@@ -235,7 +246,7 @@ while IFS= read -r -d '' page; do
     fi
 
     # Q-TEMPLATE: unreplaced {TOKEN} placeholders.
-    if body_of "$page" | grep -qE "$TOKEN_RE"; then
+    if template_scan_body "$page" | grep -qE "$TOKEN_RE"; then
         fail "$rel" "Q-TEMPLATE" "unreplaced template token {PLACEHOLDER}"
     fi
 

package/scripts/tools/okf-validate.sh

@@ -176,14 +176,25 @@ while IFS= read -r -d '' page; do
     fi
 done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 
+# Page text the {ALL_CAPS} template-token scan is allowed to see. Fenced code
+# blocks and shell-style ${VAR} expansions are removed first: both legitimately
+# contain {ALL_CAPS} spans that are NOT unreplaced placeholders, and a wiki page
+# quoting `${HOME}` or a CI snippet would otherwise fail the whole bundle.
+template_scan_text() {
+    awk '
+        /^[[:space:]]*```/ { fence = !fence; next }
+        !fence { gsub(/\$\{[A-Za-z_][A-Za-z0-9_]*\}/, ""); print }
+    ' "$1"
+}
+
 # --- 3b. Unreplaced template tokens (any page, including index pages) ---
 # Quality checks skip index.md pages, so a leftover {SECTION_TITLE}/{PROJECT_NAME}
 # placeholder in a hand-seeded index would otherwise survive. Match {ALL_CAPS}
 # tokens (safe: real prose almost never contains them).
 while IFS= read -r -d '' page; do
     prel="${page#"$BUNDLE/"}"
-    if grep -qE '\{[A-Z][A-Z0-9_]+\}' "$page" 2>/dev/null; then
-        tok="$(grep -oE '\{[A-Z][A-Z0-9_]+\}' "$page" | head -1)"
+    tok="$(template_scan_text "$page" 2>/dev/null | grep -oE '\{[A-Z][A-Z0-9_]+\}' | head -1 || true)"
+    if [[ -n "$tok" ]]; then
         add_error "$prel: unreplaced template token '$tok'"
     fi
 done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)

package/scripts/tools/parse-git-log.sh

@@ -63,6 +63,13 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
     exit 1
 fi
 
+# `git log -n <non-numeric>` parses the count as 0 and exits 0, so a typo'd
+# --limit silently yields an empty stream. Reject it here instead.
+if [[ -n "$LIMIT" && ! "$LIMIT" =~ ^[0-9]+$ ]]; then
+    echo "ERROR: --limit must be a non-negative integer (got '$LIMIT')" >&2
+    exit 1
+fi
+
 # Format: delimiter-separated metadata line, then --name-only file list, blank line separator.
 GIT_ARGS=(log --pretty=tformat:'COMMIT%x1f%H%x1f%an%x1f%aI%x1f%s' --name-only --no-merges)
 [[ -n "$SINCE" ]] && GIT_ARGS+=(--since="$SINCE")
@@ -118,6 +125,17 @@ process_commit() {
 
 # Single git log stream: each commit is `COMMIT<US>sha<US>author<US>ts<US>subject`
 # followed by its file paths (one per line) and a blank separator.
+#
+# Staged through a temp file rather than `< <(git ...)`: a process substitution
+# swallows git's exit status, so a bad --branch/--since/--limit produced an empty
+# JSONL stream and exit 0 — indistinguishable from "this range has no commits".
+GIT_OUT="$(mktemp)"
+trap 'rm -f "$GIT_OUT"' EXIT
+if ! git "${GIT_ARGS[@]}" >"$GIT_OUT"; then
+    echo "ERROR: git log failed (check --branch / --since / --limit)" >&2
+    exit 1
+fi
+
 cur_sha=""; cur_author=""; cur_ts=""; cur_subject=""; cur_files=0
 while IFS= read -r line; do
     if [[ "$line" == COMMIT$'\x1f'* ]]; then
@@ -129,7 +147,7 @@ while IFS= read -r line; do
     elif [[ -n "$line" ]]; then
         cur_files=$((cur_files + 1))
     fi
-done < <(git "${GIT_ARGS[@]}")
+done < "$GIT_OUT"
 if [[ -n "$cur_sha" ]]; then
     process_commit "$cur_sha" "$cur_author" "$cur_ts" "$cur_subject" "$cur_files"
 fi

package/scripts/tools/resolve-tools.sh

@@ -7,6 +7,14 @@
 # See core/shared/tool-resolver.md for the canonical procedure and the inline preamble
 # skills embed (this script is the single source of truth for the resolution order).
 #
+# Resolution order is deliberately "authoritative install first, cwd last":
+# skills execute whatever this prints, and the cwd is the repository under review,
+# which Draft routinely runs against untrusted code. A project that ships its own
+# scripts/tools/ must never shadow the installed plugin.
+#
+# Working on Draft itself? Export DRAFT_PLUGIN_ROOT="$PWD" — the explicit override
+# is step 1 and always wins.
+#
 # Usage:
 #   DRAFT_TOOLS="$(scripts/tools/resolve-tools.sh)"   # prints the dir, exit 0 if found
 #   scripts/tools/resolve-tools.sh || echo "tools not found"   # exit 1 if none exist
@@ -21,8 +29,18 @@ esac
 
 newest() {
   # Echo the lexically-newest existing match of a glob (by version sort), or nothing.
+  # `|| true` is load-bearing: on a glob miss `ls` exits non-zero, pipefail
+  # propagates it, and errexit would abort the whole resolver instead of letting
+  # the remaining fallbacks run.
   # shellcheck disable=SC2086
-  ls -d $1 2>/dev/null | sort -V | tail -1
+  ls -d $1 2>/dev/null | sort -V | tail -1 || true
+}
+
+# Is DIR Draft's own source checkout? Checked before trusting the cwd at all.
+is_draft_checkout() {
+  [ -f "$1/scripts/tools/resolve-tools.sh" ] || return 1
+  [ -f "$1/.claude-plugin/plugin.json" ] || return 1
+  grep -q '"name"[[:space:]]*:[[:space:]]*"draft"' "$1/.claude-plugin/plugin.json" 2>/dev/null
 }
 
 resolve() {
@@ -32,10 +50,6 @@ resolve() {
   d="${DRAFT_PLUGIN_ROOT:-}/scripts/tools"
   [ -n "${DRAFT_PLUGIN_ROOT:-}" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
 
-  # 1b. Dev / dogfooding: cwd IS the draft repo. Guarded by this script's own
-  # presence so it can never misfire in a user project (which has no resolve-tools.sh).
-  [ -f "$PWD/scripts/tools/resolve-tools.sh" ] && { printf '%s' "$PWD/scripts/tools"; return 0; }
-
   # 2. Install marker written by `draft install` (authoritative).
   local marker="$HOME/.cache/draft/plugin-root"
   if [ -f "$marker" ]; then
@@ -68,9 +82,11 @@ resolve() {
   d="$HOME/.cursor/plugins/local/draft/scripts/tools"
   [ -d "$d" ] && { printf '%s' "$d"; return 0; }
 
-  # 8. Dev / dogfooding (running inside the draft repo itself).
-  d="$PWD/scripts/tools"
-  [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+  # 8. Last resort — dev / dogfooding inside Draft's own checkout. Deliberately
+  # after every install location, and gated on the plugin manifest rather than on
+  # a same-named file: a bare `$PWD/scripts/tools` test matched any project using
+  # that very common layout and handed it script execution.
+  is_draft_checkout "$PWD" && { printf '%s' "$PWD/scripts/tools"; return 0; }
 
   return 1
 }

package/scripts/tools/verify-citations.sh

@@ -189,8 +189,7 @@ scan_one_track() {
 
     while IFS= read -r f; do
         local rel_md="${f#"$track_dir/"}"
-        while IFS=$'\t' read -r md_file lineno cite; do
-            local md_line="$md_file"
+        while IFS=$'\t' read -r _md_file lineno cite; do
             local result rc=0
             # set +e to capture rc; set -e would exit on a non-zero return.
             set +e

package/scripts/tools/verify-doc-anchors.sh

@@ -3,12 +3,16 @@
 
 #
 # Verify cross-document references in a track:
-# - §X.Y or §X numbered-section references → target document must contain
-# a heading whose text starts with that number.
 # - <doc>.md#<anchor> markdown anchors → resolve <anchor> against the
 # target file's header slugs.
 # - (planned) / [New file ...] annotations → file MUST NOT exist locally.
 #
+# Plain-prose `§X.Y` references are deliberately NOT validated: authors use them
+# as shorthand for an external doc (`architecture.md §20.2`) without naming the
+# file on the same line, so attribution is guesswork. A track that wants a
+# machine-checkable §-reference writes it as a markdown link to the heading,
+# which the anchor check above already covers.
+#
 # Skips content inside <!-- VERIFIER:IGNORE START --> ... END --> blocks.
 #
 # Usage:
@@ -35,7 +39,7 @@ TRACK_PATHS=()
 usage() {
     local stream=2 code=2
     if [[ "${USAGE_HELP_MODE:-0}" == 1 ]]; then stream=1; code=0; fi
-    sed -n '2,20p' "$0" >&$stream
+    sed -n '2,26p' "$0" >&$stream
     exit "$code"
 }
 
@@ -72,24 +76,15 @@ md_slugs() {
             s = tolower(s)
             # Replace spaces with dashes
             gsub(/ +/, "-", s)
-            # Strip punctuation except dashes
-            gsub(/[^a-z0-9-]/, "", s)
+            # Strip punctuation except dashes and underscores. GitHub keeps `_`
+            # in a heading slug (and so does _lib.sh:gfm_slug) — stripping it
+            # here reported every valid #foo_bar-style anchor as missing.
+            gsub(/[^a-z0-9_-]/, "", s)
             print s
         }
     ' "$1" | sort -u
 }
 
-# Extract numbered headers (e.g. "## 7 Parallel SST transfer" or "## 20.2 ...").
-md_numbered_headers() {
-    awk '
-        /^#{1,6} +[0-9]+(\.[0-9]+)*[ .]/ {
-            s = $0
-            sub(/^#+ +/, "", s)
-            print s
-        }
-    ' "$1"
-}
-
 scan_md() {
     local track_dir="$1" md="$2"
     local rel_track="${track_dir#"$REPO_ROOT/"}"
@@ -101,22 +96,7 @@ scan_md() {
         if [[ "$line" == *"<!-- VERIFIER:IGNORE END -->"* ]]; then ignore=0; continue; fi
         (( ignore )) && continue
 
-        # 1. §-references inside a markdown link.
-        # Plain-prose `§X.Y` is too ambiguous in practice — authors commonly
-        # use it as shorthand for an external doc (e.g. `architecture.md §20.2`)
-        # without naming the file on the same line. To keep this validator
-        # focused on machine-verifiable cross-references, we only check
-        # §X.Y when it appears INSIDE a markdown link target — i.e. the
-        # author has structurally committed to an in-track reference.
-        # Example that IS validated:
-        # [see §3.1](./hld.md#detailed-design) ← anchor check below
-        # Example that is NOT validated (prose only):
-        # The §20.2 layout matches architecture.md.
-        # If a track wants stricter intra-track §-checks, it can use
-        # markdown links pointing to numbered headers explicitly.
-        : # §-ref prose validation disabled — see comment above.
-
-        # 2. Markdown anchor references like ./hld.md#section-name
+        # 1. Markdown anchor references like ./hld.md#section-name
         if echo "$line" | grep -qE '\([^)]*\.md#[A-Za-z0-9_-]+\)'; then
             local m
             while IFS= read -r m; do
@@ -141,7 +121,7 @@ scan_md() {
             done < <(echo "$line" | grep -oE '\([^)]*\.md#[A-Za-z0-9_-]+\)')
         fi
 
-        # 3. (planned) / [New file ...] annotations: the path mentioned on the
+        # 2. (planned) / [New file ...] annotations: the path mentioned on the
         # same line must NOT yet exist relative to the track.
         #
         # Only fire when the line has EXACTLY one path-looking token. Lines

package/scripts/tools/verify-graph-binary.sh

@@ -2,6 +2,7 @@
 # verify-graph-binary.sh — validate and select the Draft knowledge-graph engine.
 #
 # The engine is the codebase-memory-mcp binary. Resolution order (see _lib.sh:find_memory_bin):
+#   0. DRAFT_MEMORY_DISABLE — hard off; resolution stops here and reports "none"
 #   1. DRAFT_MEMORY_BIN override
 #   2. codebase-memory-mcp on $PATH
 #   3. Draft-managed install (~/.cache/draft/bin/)
@@ -32,7 +33,8 @@ usage() {
 verify-graph-binary.sh — Draft knowledge-graph engine resolver + verifier
 
 Engine: codebase-memory-mcp
-Resolution: DRAFT_MEMORY_BIN > PATH > ~/.cache/draft/bin > bin/<arch>/
+Resolution: DRAFT_MEMORY_DISABLE (hard off) > DRAFT_MEMORY_BIN > PATH
+            > ~/.cache/draft/bin > bin/<arch>/
 
 Options:
   --repo DIR         Repo root for context (default .)
@@ -95,15 +97,23 @@ classify_source() {
 
 MEMORY_BIN=""
 if ! find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
-  if [[ $EMIT_JSON -eq 1 ]]; then
+  # DRAFT_MEMORY_DISABLE short-circuits resolution, so say so — "install it or
+  # put it on PATH" is the wrong remedy when an env var turned the engine off.
+  if [[ -n "${DRAFT_MEMORY_DISABLE:-}" ]]; then
+    local_msg="Graph engine disabled by DRAFT_MEMORY_DISABLE (unset it to re-enable resolution)"
+  else
     local_msg="No codebase-memory-mcp engine found in DRAFT_MEMORY_BIN, PATH, ~/.cache/draft/bin, or bin/<arch>/"
+  fi
+  if [[ $EMIT_JSON -eq 1 ]]; then
     if [[ $STRICT -eq 1 ]]; then
       printf '{"status":"none","engine_bin":null,"source":null,"arch":"%s","message":"strict mode: %s"}\n' "$ARCH" "$local_msg"
     else
       printf '{"status":"unavailable","engine_bin":null,"source":null,"arch":"%s","message":"%s"}\n' "$ARCH" "$local_msg"
     fi
   elif [[ $STRICT -eq 1 ]]; then
-    echo "STRICT: No codebase-memory-mcp engine found." >&2
+    echo "STRICT: $local_msg" >&2
+  elif [[ -n "${DRAFT_MEMORY_DISABLE:-}" ]]; then
+    echo "ERROR: $local_msg" >&2
   else
     echo "ERROR: No Draft graph engine located (codebase-memory-mcp)." >&2
     echo "        Install it (scripts/fetch-memory-engine.sh) or put it on PATH." >&2