@drafthq/draft 3.5.3 → 3.6.0

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

@@ -73,13 +73,13 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --scope) SCOPE="$2"; shift 2;;
-        --manifest) MANIFEST="$2"; shift 2;;
-        --min-fan-in) MIN_FAN_IN="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --scope) SCOPE="${2:?--scope requires a value}"; shift 2;;
+        --manifest) MANIFEST="${2:?--manifest requires a value}"; shift 2;;
+        --min-fan-in) MIN_FAN_IN="${2:?--min-fan-in requires a value}"; shift 2;;
         --defer-below-floor) DEFER_BELOW_FLOOR=1; shift;;
         --allow-defer) ALLOW_DEFER+=("$2"); shift 2;;
-        --out) OUT="$2"; shift 2;;
+        --out) OUT="${2:?--out requires a value}"; shift 2;;
         --json) JSON=1; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -111,13 +111,38 @@ is_deferred_name() {
 E_ID=(); E_TYPE=(); E_RES=(); E_FANIN=(); E_REQ=(); E_REASON=()
 SOURCE="heuristic"
 DEGRADED="false"
+DISCOVERY_META=()   # e.g. cargo, npm, go, graph, heuristic
+
+# Graph package names that are almost always tokenizer/type noise, not modules.
+is_noise_package_name() {
+    local n="$1"
+    case "$n" in
+        str|list|dict|int|bool|float|string|type|mod|Cargo|cargo|profile|int64|uint|byte|char|void|null|None|true|false|i32|i64|u32|u64|f32|f64|Option|Result|Error|Self|self)
+            return 0;;
+    esac
+    return 1
+}
+
+# True if concept_id already recorded.
+has_concept_id() {
+    local want="$1" id
+    for id in "${E_ID[@]:-}"; do
+        [[ "$id" == "$want" ]] && return 0
+    done
+    return 1
+}
 
 add_concept() {
     # name section type resource fan_in required reason
     local name="$1" section="$2" type="$3" resource="$4" fan_in="$5" required="$6" reason="$7"
     local stem; stem="$(slug "$name")"
     [[ -n "$stem" ]] || stem="component"
-    E_ID+=("$section/$stem.md")
+    local cid="$section/$stem.md"
+    # Dedupe by concept_id (cargo + graph may both see the same crate).
+    if has_concept_id "$cid"; then
+        return 0
+    fi
+    E_ID+=("$cid")
     E_TYPE+=("$type")
     E_RES+=("$resource")
     E_FANIN+=("$fan_in")
@@ -141,29 +166,195 @@ plan_from_manifest() {
     SOURCE="manifest"
 }
 
-# --- 2. Graph path ---
+# --- 2a. Language-aware workspace inventories (Cargo / npm / Go) ---
+# These produce crate/package-level concepts that graph .packages often collapse
+# or mis-label (especially Rust monorepos). Prefer path-grounded resources.
+
+plan_from_cargo_workspace() {
+    local cargo="$REPO/Cargo.toml"
+    [[ -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
+
+    local members=()
+    # Extract quoted paths inside the members = [ ... ] array (possibly multi-line).
+    local in_members=0 line m
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        if [[ "$line" =~ members[[:space:]]*=[[:space:]]*\[ ]]; then
+            in_members=1
+        fi
+        if [[ $in_members -eq 1 ]]; then
+            while [[ "$line" =~ \"([^\"]+)\" ]]; do
+                m="${BASH_REMATCH[1]}"
+                members+=("$m")
+                line="${line#*\"$m\"}"
+            done
+            [[ "$line" == *"]"* ]] && in_members=0
+        fi
+    done < "$cargo"
+
+    [[ ${#members[@]} -gt 0 ]] || return 1
+
+    local path name ct required reason type
+    local added=0
+    for path in "${members[@]}"; do
+        [[ -z "$path" ]] && continue
+        # Skip globs we can't expand cheaply without bash nullglob walk
+        if [[ "$path" == *"*"* ]]; then
+            local base="${path%%/\*}"
+            [[ -d "$REPO/$base" ]] || continue
+            while IFS= read -r ct; do
+                name="$(basename "$(dirname "$ct")")"
+                [[ -z "$name" ]] && continue
+                if is_deferred_name "$name"; then
+                    required=false; reason="allow-defer match"
+                else
+                    required=true; reason=""
+                fi
+                type=Module
+                # Entrypoint packaging root if only main.rs and no lib.rs (heuristic)
+                if [[ -f "$(dirname "$ct")/src/main.rs" && ! -f "$(dirname "$ct")/src/lib.rs" ]]; then
+                    type=Module
+                fi
+                add_concept "$name" systems "$type" "$(dirname "$ct" | sed "s|^$REPO/||")" 0 "$required" "$reason"
+                added=$((added+1))
+            done < <(find "$REPO/$base" -mindepth 1 -maxdepth 3 -type f -name 'Cargo.toml' 2>/dev/null | sort)
+            continue
+        fi
+        [[ -f "$REPO/$path/Cargo.toml" || -f "$REPO/$path" ]] || continue
+        local res="$path"
+        [[ -f "$REPO/$path" && "$path" == */Cargo.toml ]] && res="$(dirname "$path")"
+        name="$(basename "$res")"
+        if is_deferred_name "$name"; then
+            required=false; reason="allow-defer match"
+        else
+            required=true; reason=""
+        fi
+        add_concept "$name" systems Module "$res" 0 "$required" "$reason"
+        added=$((added+1))
+    done
+    [[ $added -gt 0 ]] || return 1
+    DISCOVERY_META+=("cargo")
+    return 0
+}
+
+plan_from_npm_workspaces() {
+    local pkg="$REPO/package.json"
+    [[ -f "$pkg" ]] || return 1
+    command -v jq >/dev/null 2>&1 || return 1
+    # workspaces may be array or { packages: [] }
+    local names
+    names="$(jq -r '
+        if .workspaces|type=="array" then .workspaces[]
+        elif .workspaces.packages|type=="array" then .workspaces.packages[]
+        else empty end
+    ' "$pkg" 2>/dev/null || true)"
+    [[ -n "$names" ]] || return 1
+    local path name required reason added=0
+    while IFS= read -r path; do
+        [[ -z "$path" || "$path" == *"*"* ]] && continue
+        name="$(basename "$path")"
+        if is_deferred_name "$name"; then
+            required=false; reason="allow-defer match"
+        else
+            required=true; reason=""
+        fi
+        add_concept "$name" systems Module "$path" 0 "$required" "$reason"
+        added=$((added+1))
+    done <<< "$names"
+    [[ $added -gt 0 ]] || return 1
+    DISCOVERY_META+=("npm")
+    return 0
+}
+
+plan_from_go_modules() {
+    # go.work use directives, else single go.mod at root, else first-level */go.mod
+    local added=0 name required reason path
+    if [[ -f "$REPO/go.work" ]]; then
+        while IFS= read -r path; do
+            path="$(printf '%s' "$path" | sed -E 's/^[[:space:]]*//')"
+            [[ -z "$path" || "$path" == //* ]] && continue
+            [[ -f "$REPO/$path/go.mod" ]] || continue
+            name="$(basename "$path")"
+            if is_deferred_name "$name"; then
+                required=false; reason="allow-defer match"
+            else
+                required=true; reason=""
+            fi
+            add_concept "$name" systems Module "$path" 0 "$required" "$reason"
+            added=$((added+1))
+        done < <(awk '/^use[[:space:]]*\(/,/^\)/ {if ($1!="use" && $1!="(" && $1!=")") print $1}
+                      /^use[[:space:]]+\./ {print $2}' "$REPO/go.work" | tr -d '"')
+    fi
+    if [[ $added -eq 0 && -f "$REPO/go.mod" ]]; then
+        name="$(basename "$REPO")"
+        add_concept "$name" systems Module "." 0 true ""
+        added=1
+    fi
+    if [[ $added -eq 0 ]]; then
+        while IFS= read -r path; do
+            name="$(basename "$(dirname "$path")")"
+            add_concept "$name" systems Module "$(dirname "$path" | sed "s|^$REPO/||")" 0 true ""
+            added=$((added+1))
+        done < <(find "$REPO" -mindepth 2 -maxdepth 3 -type f -name 'go.mod' 2>/dev/null | sort | head -50)
+    fi
+    [[ $added -gt 0 ]] || return 1
+    DISCOVERY_META+=("go")
+    return 0
+}
+
+# --- 2b. Graph path ---
 plan_from_graph() {
     local arch; arch="$(scripts_graph_arch)" || return 1
     [[ -n "$arch" ]] || return 1
     echo "$arch" | jq -e '.packages != null' >/dev/null 2>&1 || return 1
 
-    SOURCE="graph"
+    local have_lang_inventory=0
+    [[ ${#DISCOVERY_META[@]} -gt 0 ]] && have_lang_inventory=1
+
     local name fan_in type required reason
     # Packages → systems/<pkg>.md
     while IFS=$'\t' read -r name fan_in; do
         [[ -z "$name" ]] && continue
+        # Drop tokenizer noise when we already have a real inventory (cargo/npm/go).
+        if [[ $have_lang_inventory -eq 1 ]] && is_noise_package_name "$name"; then
+            continue
+        fi
+        # Even without inventory, skip pure noise names that do not map to a dir.
+        if is_noise_package_name "$name"; then
+            local mapped=0
+            for d in "$REPO/$name" "$REPO/crates/$name" "$REPO/src/$name" "$REPO/third_party/$name"; do
+                [[ -d "$d" ]] && mapped=1 && break
+            done
+            [[ $mapped -eq 0 ]] && continue
+        fi
         if is_deferred_name "$name"; then
             required=false; reason="allow-defer match"; type=Module
         elif (( fan_in >= MIN_FAN_IN )); then
             required=true; reason=""; type=Subsystem
         elif [[ $DEFER_BELOW_FLOOR -eq 1 ]]; then
-            # Opt-in legacy behavior: low-fan-in packages are exempted.
             required=false; reason="fan_in $fan_in < floor $MIN_FAN_IN"; type=Module
         else
-            # Default: every package the graph knows about is documented. Fan-in
-            # below the floor only demotes Subsystem→Module; it never exempts.
             required=true; reason=""; type=Module
         fi
+        # When language inventory exists, graph packages that are coarse parents
+        # (e.g. codegen/) become Subsystems only if a matching directory exists.
+        if [[ $have_lang_inventory -eq 1 ]]; then
+            if [[ -d "$REPO/$name" || -d "$REPO/crates/$name" || -d "$REPO/third_party/$name" || -d "$REPO/prod/$name" ]]; then
+                type=Subsystem
+                # Prefer real path as resource when known
+                for d in "$name" "crates/$name" "third_party/$name" "prod/$name"; do
+                    if [[ -d "$REPO/$d" ]]; then
+                        add_concept "$name" systems "$type" "$d" "$fan_in" "$required" "$reason"
+                        continue 2
+                    fi
+                done
+            else
+                # Unmapped graph label with inventory present → skip (not a crate).
+                continue
+            fi
+        fi
         add_concept "$name" systems "$type" "$name" "$fan_in" "$required" "$reason"
     done < <(echo "$arch" | jq -r '.packages[]? | [.name, (.fan_in // 0)] | @tsv')
 
@@ -178,6 +369,8 @@ plan_from_graph() {
     done < <(echo "$arch" | jq -r '
         (.entry_points // [])[]? | if type=="object" then (.name // .path // empty) else . end' \
         | sort -u)
+    DISCOVERY_META+=("graph")
+    return 0
 }
 
 # graph-arch.sh wrapper that tolerates the "unavailable" sentinel.
@@ -218,13 +411,30 @@ plan_from_heuristic() {
 }
 
 # --- Drive discovery in priority order ---
+# 1. --manifest (authoritative, exclusive)
+# 2. Language inventories (Cargo / npm / Go) — can combine with graph parents
+# 3. Graph packages (filtered when inventory present)
+# 4. Heuristic top-level dirs
 if [[ -n "$MANIFEST" ]]; then
     [[ -f "$MANIFEST" ]] || { echo "ERROR: --manifest not found: $MANIFEST" >&2; exit 1; }
     plan_from_manifest
-elif plan_from_graph; then
-    :
+    DISCOVERY_META+=("manifest")
 else
-    plan_from_heuristic
+    # Language inventories first so cargo crate names win concept_ids.
+    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.
+    if [[ ${#E_ID[@]} -eq 0 ]]; then
+        plan_from_heuristic
+        DISCOVERY_META+=("heuristic")
+    fi
 fi
 
 if [[ ${#E_ID[@]} -eq 0 ]]; then
@@ -232,6 +442,19 @@ if [[ ${#E_ID[@]} -eq 0 ]]; then
     exit 2
 fi
 
+# Compose SOURCE label from discovery meta
+if [[ ${#DISCOVERY_META[@]} -gt 0 ]]; then
+    # de-dupe meta labels
+    SOURCE="$(printf '%s\n' "${DISCOVERY_META[@]}" | awk '!s[$0]++' | paste -sd+ -)"
+    [[ -z "$SOURCE" ]] && SOURCE="heuristic"
+    # degraded only when pure heuristic with no language/graph
+    if [[ "$SOURCE" == "heuristic" ]]; then
+        DEGRADED="true"
+    else
+        DEGRADED="false"
+    fi
+fi
+
 # Required-first, then deferred; stable within group (topological-ish: high fan-in
 # subsystems first so forward cross-links resolve during generation).
 emit_plan() {
@@ -257,6 +480,14 @@ emit_plan() {
         printf '  "source": "%s",\n' "$SOURCE"
         printf '  "degraded": %s,\n' "$DEGRADED"
         printf '  "min_fan_in": %d,\n' "$MIN_FAN_IN"
+        printf '  "discovery": ['
+        local di first_d=1
+        for di in "${DISCOVERY_META[@]:-}"; do
+            [[ -z "$di" ]] && continue
+            [[ $first_d -eq 1 ]] && first_d=0 || printf ','
+            printf '"%s"' "$(json_escape "$di")"
+        done
+        printf '],\n'
         # generated_order
         printf '  "generated_order": ['
         local first=1

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

@@ -62,12 +62,12 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --arch-out) ARCH_OUT="$2"; shift 2;;
+        --arch-out) ARCH_OUT="${2:?--arch-out requires a value}"; shift 2;;
         --concept-map-into) CMAP_INTO+=("$2"); shift 2;;
         --section-indexes) SECTION_INDEXES=1; shift;;
-        --web) WEB_OUT="$2"; shift 2;;
-        --coverage-report) COVERAGE_REPORT="$2"; shift 2;;
-        --validated-at) VALIDATED_AT="$2"; shift 2;;
+        --web) WEB_OUT="${2:?--web requires a value}"; shift 2;;
+        --coverage-report) COVERAGE_REPORT="${2:?--coverage-report requires a value}"; shift 2;;
+        --validated-at) VALIDATED_AT="${2:?--validated-at requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *)
@@ -101,6 +101,38 @@ ordered_pages() {
 }
 
 # 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() {
+    local rel="${1:-}"
+    local sec="${rel%%/*}"
+    python3 -c '
+import sys, re
+sec = sys.argv[1]
+text = sys.stdin.read()
+sections = ("systems", "features", "overview", "entrypoints", "reference")
+def repl(m):
+    label, href = m.group(1), m.group(2).strip()
+    if href.startswith(("http://", "https://", "mailto:", "#", "wiki/")):
+        return m.group(0)
+    if "::" in href and not href.startswith("../"):
+        return "`" + label + "`"
+    path, _, frag = href.partition("#")
+    frag_s = "#" + frag if frag else ""
+    if path.startswith("../"):
+        rest = path[3:]
+        if rest.split("/")[0] in sections:
+            return "[%s](wiki/%s%s)" % (label, rest, frag_s)
+    if any(path.startswith(s + "/") for s in sections):
+        return "[%s](wiki/%s%s)" % (label, path, frag_s)
+    if path.endswith(".md") and "/" not in path and sec in sections:
+        return "[%s](wiki/%s/%s%s)" % (label, sec, path, frag_s)
+    return m.group(0)
+sys.stdout.write(re.sub(r"\[([^\]]*)\]\(([^)]+)\)", repl, text))
+' "$sec"
+}
+
 strip_frontmatter() {
     awk '
         NR==1 && /^---$/ { fm=1; next }
@@ -172,8 +204,7 @@ render_architecture() {
             fi
             title="$(page_title "$BUNDLE/$rel")"
             [[ -n "$title" ]] || title="$rel"
-            local anchor; anchor="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')"
-            anchor="${anchor#-}"; anchor="${anchor%-}"
+            local anchor; anchor="$(gfm_slug "$title")"
             echo "  - [${title}](#${anchor})"
         done < <(ordered_pages)
         echo ""
@@ -183,10 +214,16 @@ render_architecture() {
             echo ""
             echo "---"
             echo ""
-            strip_frontmatter "$BUNDLE/$rel"
+            strip_frontmatter "$BUNDLE/$rel" | rewrite_body_links "$rel"
         done < <(ordered_pages)
     } >"$tmp"
     mv "$tmp" "$out"
+    if [[ -x "$SCRIPT_DIR/okf-fix-links.sh" ]]; then
+        draft_dir="$(cd "$(dirname "$out")" && pwd)"
+        if [[ -d "$draft_dir/wiki" || "$(basename "$BUNDLE")" == "wiki" ]]; then
+            "$SCRIPT_DIR/okf-fix-links.sh" --file "$out" --wiki "$BUNDLE" --fix >/dev/null 2>&1 || true
+        fi
+    fi
     echo "rendered architecture view → $out ($(ordered_pages | grep -c . ) pages)"
 }
 
@@ -387,7 +424,7 @@ function render(md, base){
   var blocks=[], src=md.replace(/```(\w*)\n([\s\S]*?)```/g,function(m,lang,body){
     var cls = lang==='mermaid' ? ' class="mermaid-src"' : '';
     blocks.push('<pre'+cls+'><code>'+esc(body.replace(/\n$/,''))+'</code></pre>');
-    return 'BLOCK'+(blocks.length-1)+'';
+    return 'BLOCK'+(blocks.length-1)+'';
   });
   var lines=src.split('\n'), out='', i=0, list='', tbl=[];
   function closeList(){ if(list){ out+='</'+list+'>'; list=''; } }
@@ -410,7 +447,7 @@ function render(md, base){
     if(/^\s*>\s?/.test(ln)){ closeList(); out+='<blockquote>'+inline(esc(ln.replace(/^\s*>\s?/,'')),base)+'</blockquote>'; continue; }
     var li=ln.match(/^\s*([-*]|\d+\.)\s+(.*)$/);
     if(li){ var want=/^\d/.test(li[1])?'ol':'ul'; if(list!==want){ closeList(); list=want; out+='<'+want+'>'; } out+='<li>'+inline(esc(li[2]),base)+'</li>'; continue; }
-    var b=ln.match(/^BLOCK(\d+)$/);
+    var b=ln.match(/^BLOCK(\d+)$/);
     if(b){ closeList(); out+=blocks[+b[1]]; continue; }
     if(/^\s*$/.test(ln)){ closeList(); continue; }
     closeList(); out+='<p>'+inline(esc(ln),base)+'</p>';

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

@@ -6,9 +6,10 @@
 # code, so a bundle that is structurally broken, full of stubs, or missing
 # required components is never promoted.
 #
-#   Layer 1  okf-validate.sh          structure (frontmatter, types, links, index)
 #   Layer 2  okf-validate-quality.sh  per-type anti-stub / depth / mermaid lint
 #   Layer 3  okf-coverage-check.sh    every required plan entry has a real page
+#                                      (may rewrite systems/coverage.md)
+#   Layer 1  okf-validate.sh          structure LAST so coverage rewrite is checked
 #
 # Usage:
 #   okf-validate-all.sh <BUNDLE_DIR> [--plan FILE] [--path-index FILE]
@@ -53,10 +54,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --plan) PLAN="$2"; shift 2;;
-        --path-index) PATH_INDEX="$2"; shift 2;;
+        --plan) PLAN="${2:?--plan requires a value}"; shift 2;;
+        --path-index) PATH_INDEX="${2:?--path-index requires a value}"; shift 2;;
         --strict) STRICT=1; shift;;
-        --report) REPORT="$2"; shift 2;;
+        --report) REPORT="${2:?--report requires a value}"; shift 2;;
         --json) JSON=1; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -79,16 +80,23 @@ run_layer() {
     return $rc
 }
 
-# Layer 1: structure.
+# Order matters:
+#   1) quality  — page content (does not rewrite files)
+#   2) coverage — may REGENERATE systems/coverage.md (tool-owned)
+#   3) structure — link/frontmatter check LAST so coverage rewrite cannot leave
+#                  dangling links that structure already approved.
+#
+# Historical bug: structure-before-coverage let init promote a bundle whose
+# coverage.md still had broken relative links (entrypoints/ from systems/).
+
 v1_args=("$BUNDLE")
 [[ -n "$PATH_INDEX" ]] && v1_args+=(--path-index "$PATH_INDEX")
-if run_layer structure "$SCRIPT_DIR/okf-validate.sh" "${v1_args[@]}"; then L1=pass; else L1=fail; OVERALL=1; fi
-
-# Layer 2: quality.
 q_args=("$BUNDLE"); [[ $STRICT -eq 1 ]] && q_args+=(--strict)
+
+# Layer 2: quality (run first for fast fail on stubs).
 if run_layer quality "$SCRIPT_DIR/okf-validate-quality.sh" "${q_args[@]}"; then L2=pass; else L2=fail; OVERALL=1; fi
 
-# Layer 3: coverage (only if a plan is supplied).
+# Layer 3: coverage (writes coverage.md when not --no-coverage-page).
 if [[ -n "$PLAN" ]]; then
     if run_layer coverage "$SCRIPT_DIR/okf-coverage-check.sh" --plan "$PLAN" --bundle "$BUNDLE"; then
         L3=pass
@@ -97,6 +105,9 @@ if [[ -n "$PLAN" ]]; then
     fi
 fi
 
+# Layer 1: structure LAST (after coverage page is final).
+if run_layer structure "$SCRIPT_DIR/okf-validate.sh" "${v1_args[@]}"; then L1=pass; else L1=fail; OVERALL=1; fi
+
 REPORT_JSON="$(printf '{"valid":%s,"bundle":"%s","layers":{"structure":"%s","quality":"%s","coverage":"%s"}}\n' \
     "$([[ $OVERALL -eq 0 ]] && echo true || echo false)" "$(json_escape "$BUNDLE")" "$L1" "$L2" "$L3")"
 

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

@@ -76,15 +76,9 @@ body_of() {
 # Count body lines after the frontmatter close (Q-LEN = "lines after frontmatter").
 body_lines() { body_of "$1" | wc -l | tr -d ' '; }
 
-# x-grounded-paths array length (entries inside [ ... ]).
+# x-grounded-paths array length — inline `[a, b]` or YAML block list (via _lib.sh).
 grounded_count() {
-    local arr
-    arr="$(grep -m1 -E '^x-grounded-paths:' "$1" 2>/dev/null || true)"
-    [[ -z "$arr" ]] && { echo 0; return; }
-    arr="${arr#*[}"; arr="${arr%]*}"
-    arr="$(printf '%s' "$arr" | tr -d ' ')"
-    [[ -z "$arr" ]] && { echo 0; return; }
-    awk -F',' '{print NF}' <<< "$arr"
+    grounded_paths_count "$1"
 }
 
 has_section() { grep -qE "^##[[:space:]]+$1([[:space:]]|$)" "$2"; }

package/scripts/tools/okf-validate.sh

@@ -66,7 +66,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --path-index) PATH_INDEX="$2"; shift 2;;
+        --path-index) PATH_INDEX="${2:?--path-index requires a value}"; shift 2;;
         --reverse) REVERSE=1; shift;;
         --structure-only) STRUCTURE_ONLY=1; shift;;
         --json) JSON=1; shift;;
@@ -237,12 +237,14 @@ if [[ -n "$PATH_INDEX" ]]; then
         # themselves end in .md (e.g. grounding to docs/INVARIANTS.md) — those are
         # not bundle pages, so we extract strings *inside* the [ ... ] value arrays
         # and ignore keys entirely. Each page must exist in the bundle.
+        # Flatten first: the index may be pretty-printed, so value arrays can
+        # span lines and a line-oriented match would silently skip them.
         while IFS= read -r ref; do
             [[ -z "$ref" ]] && continue
             if [[ ! -f "$BUNDLE/$ref" ]]; then
                 add_error "path-index references missing concept page: $ref"
             fi
-        done < <(grep -oE '\[[^]]*\]' "$PATH_INDEX" 2>/dev/null \
+        done < <(tr '\n' ' ' < "$PATH_INDEX" 2>/dev/null | grep -oE '\[[^]]*\]' \
                    | grep -oE '"[^"]+\.md"' | tr -d '"' | sort -u)
     fi
 fi
@@ -251,9 +253,10 @@ fi
 # Forward proves the index doesn't name ghosts; reverse proves no page is an
 # orphan with no source mapping (a symptom of hand-written / off-plan pages).
 if [[ $REVERSE -eq 1 && $STRUCTURE_ONLY -eq 0 && -n "$PATH_INDEX" && -f "$PATH_INDEX" ]]; then
-    # All pages the index maps to (its array values).
+    # All pages the index maps to (its array values). Flattened for the same
+    # pretty-printed-array reason as the forward check above.
     INDEXED_FILE="$(mktemp)"
-    grep -oE '\[[^]]*\]' "$PATH_INDEX" 2>/dev/null \
+    tr '\n' ' ' < "$PATH_INDEX" 2>/dev/null | grep -oE '\[[^]]*\]' \
         | grep -oE '"[^"]+\.md"' | tr -d '"' | sort -u > "$INDEXED_FILE" || true
     while IFS= read -r -d '' page; do
         rel="${page#"$BUNDLE/"}"

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

@@ -49,10 +49,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --since) SINCE="$2"; shift 2;;
-        --limit) LIMIT="$2"; shift 2;;
-        --scope-pattern) SCOPE_PATTERN="$2"; shift 2;;
-        --branch) BRANCH="$2"; shift 2;;
+        --since) SINCE="${2:?--since requires a value}"; shift 2;;
+        --limit) LIMIT="${2:?--limit requires a value}"; shift 2;;
+        --scope-pattern) SCOPE_PATTERN="${2:?--scope-pattern requires a value}"; shift 2;;
+        --branch) BRANCH="${2:?--branch requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/parse-reports.sh

@@ -35,7 +35,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/render-track.sh

@@ -48,7 +48,7 @@ TO_STDOUT=0
 while (($#)); do
     case "$1" in
         -h|--help) USAGE_HELP_MODE=1 usage ;;
-        --out) OUT_PATH="$2"; shift 2 ;;
+        --out) OUT_PATH="${2:?--out requires a value}"; shift 2 ;;
         --stdout) TO_STDOUT=1; shift ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) TRACK_DIR="$1"; shift ;;

package/scripts/tools/run-coverage.sh

@@ -51,7 +51,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --path) COVERAGE_PATH="$2"; shift 2;;
+        --path) COVERAGE_PATH="${2:?--path requires a value}"; shift 2;;
         --schema-check) SCHEMA_CHECK="true"; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;

package/scripts/tools/scan-markers.sh

@@ -6,7 +6,7 @@
 #
 # Usage:
 # scripts/tools/scan-markers.sh [--root DIR] [--markers LIST]
-# [--min-age-days N] [--include-untracked]
+# [--min-age-days N]
 #
 # Exit codes: 0 OK (even with zero hits), 1 invocation error, 2 not a git repo
 # (emits [] on stdout so consumers can still parse).
@@ -38,9 +38,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
-        --markers) MARKERS="$2"; shift 2;;
-        --min-age-days) MIN_AGE="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
+        --markers) MARKERS="${2:?--markers requires a value}"; shift 2;;
+        --min-age-days) MIN_AGE="${2:?--min-age-days requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/validate-frontmatter.sh

@@ -43,8 +43,8 @@ REQUIRED="name,description"
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --require) REQUIRED="$2"; shift 2;;
-        --mode) MODE="$2"; shift 2;;
+        --require) REQUIRED="${2:?--require requires a value}"; shift 2;;
+        --mode) MODE="${2:?--mode requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *)

package/scripts/tools/verify-citations.sh

@@ -48,7 +48,7 @@ while (($#)); do
     case "$1" in
         -h|--help) USAGE_HELP_MODE=1 usage ;;
         --json) EMIT_JSON=1; shift ;;
-        --tolerance) TOLERANCE="$2"; shift 2 ;;
+        --tolerance) TOLERANCE="${2:?--tolerance requires a value}"; shift 2 ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) TRACK_PATHS+=("$1"); shift ;;
     esac
@@ -83,7 +83,7 @@ extract_citations() {
             # bracket expression prematurely terminates a regex literal in
             # POSIX/BSD awk ("nonterminated character class"), though gawk is
             # lenient. The string form is portable across awk implementations.
-            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+")) {
+            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+(-[0-9]+)?")) {
                 cite = substr(s, RSTART, RLENGTH)
                 printf("%s\t%d\t%s\n", FILENAME, NR, cite)
                 s = substr(s, RSTART + RLENGTH)