@drafthq/draft 3.6.0 → 3.7.1

package/scripts/tools/graph-query.sh

@@ -8,7 +8,9 @@
 #                                are rejected before the engine ever sees them).
 #   --tool NAME --json '{...}'   passthrough to any read-only engine tool
 #                                (get_code_snippet, search_graph, get_graph_schema,
-#                                trace_path, …). Destructive tools are rejected.
+#                                trace_path, …). Destructive tools are rejected, and
+#                                a `query` field in --json is scanned for write
+#                                verbs exactly like --cypher.
 #
 # Dialect limits (engine v0.8.x — see _graph_queries.sh for the full list):
 #   SAFE   : fixed-length patterns, `=`, `<`, `STARTS WITH`, `NOT x STARTS WITH`,
@@ -46,7 +48,8 @@ Flags:
   --cypher STR   Read-only openCypher query (write verbs CREATE/MERGE/DELETE/SET/
                  REMOVE/DROP/DETACH are rejected). The {project} is injected.
   --tool NAME    Engine tool to call (read-only allowlist). Combine with --json.
-  --json STR     JSON args for --tool (the project is injected if absent).
+  --json STR     JSON args for --tool (the project is injected if absent). A
+                 `query` field is write-verb checked like --cypher.
   --help         Show this help.
 
 Dialect: avoid coalesce(), <>, NOT EXISTS, NOT(pattern), WITH-aggregation,
@@ -89,13 +92,74 @@ if [[ -n "$TOOL" ]]; then
     }
 fi
 
-# Reject write verbs in --cypher BEFORE the engine sees the query.
-if [[ -n "$CYPHER" ]]; then
-    UPPER="$(printf '%s' "$CYPHER" | tr '[:lower:]' '[:upper:]')"
-    if printf '%s' "$UPPER" | grep -Eqw 'CREATE|MERGE|DELETE|SET|REMOVE|DROP|DETACH'; then
+# Drop the contents of every quoted span before scanning for write verbs below.
+# A raw substring grep can't tell a CREATE/SET/DELETE clause from a symbol
+# literally named 'create', 'set', 'delete', etc. — exactly the method names
+# real codebases are full of — so quoted spans must be blanked out first or
+# every query about one of them gets wrongly rejected. Cypher quotes strings
+# with either ' or " and identifiers with `, and the engine accepts all three,
+# so all three must be handled. Escaped quotes (`\'`, produced by gq_escape in
+# _graph_queries.sh) must not be read as closing a span early, and an
+# unterminated span fails closed (rejected) rather than letting the rest of the
+# query — write verbs included — go unscanned.
+strip_quoted_spans() {
+    local s="$1" out="" i=0 len ch quote
+    len="${#s}"
+    while (( i < len )); do
+        ch="${s:i:1}"
+        if [[ "$ch" != "'" && "$ch" != '"' && "$ch" != '`' ]]; then
+            out+="$ch"
+            i=$((i + 1))
+            continue
+        fi
+        quote="$ch"
+        out+="$quote"
+        i=$((i + 1))
+        while :; do
+            (( i < len )) || return 1
+            ch="${s:i:1}"
+            if [[ "$ch" == '\' ]]; then
+                i=$((i + 2))
+                continue
+            fi
+            i=$((i + 1))
+            if [[ "$ch" == "$quote" ]]; then
+                out+="$quote"
+                break
+            fi
+        done
+    done
+    printf '%s' "$out"
+}
+
+# Reject write verbs BEFORE the engine sees the query.
+reject_write_verbs() {
+    local stripped upper
+    stripped="$(strip_quoted_spans "$1")" || {
+        echo "ERROR: write verbs are not allowed (read-only passthrough)" >&2
+        exit 1
+    }
+    upper="$(printf '%s' "$stripped" | tr '[:lower:]' '[:upper:]')"
+    if printf '%s' "$upper" | grep -Eqw 'CREATE|MERGE|DELETE|SET|REMOVE|DROP|DETACH'; then
         echo "ERROR: write verbs are not allowed (read-only passthrough)" >&2
         exit 1
     fi
+}
+
+if [[ -n "$CYPHER" ]]; then
+    reject_write_verbs "$CYPHER"
+fi
+
+# --tool carries Cypher too: query_graph takes it in the payload's `query` field,
+# so guarding only --cypher left the read-only contract fully bypassable via
+# `--tool query_graph --json '{"query":"MATCH (n) DETACH DELETE n"}'`. Scan any
+# `query` a tool payload carries, not just query_graph's, so a future
+# query-bearing tool is covered by construction. jq-gated: without jq nothing can
+# reach the engine anyway (graph_bootstrap fails first).
+if [[ -n "$TOOL" ]] && command -v jq >/dev/null 2>&1; then
+    echo "$TOOL_JSON" | jq -e . >/dev/null 2>&1 || { echo "ERROR: --json is not valid JSON" >&2; exit 1; }
+    TOOL_QUERY="$(echo "$TOOL_JSON" | jq -r '.query // empty' 2>/dev/null || true)"
+    [[ -z "$TOOL_QUERY" ]] || reject_write_verbs "$TOOL_QUERY"
 fi
 
 unavailable() { echo '{"source":"unavailable"}'; exit 2; }
@@ -108,7 +172,6 @@ if [[ -n "$CYPHER" ]]; then
     printf '%s\n' "$RES"
 else
     # Inject the resolved project into the tool args unless the caller set one.
-    echo "$TOOL_JSON" | jq -e . >/dev/null 2>&1 || { echo "ERROR: --json is not valid JSON" >&2; exit 1; }
     ARGS="$(echo "$TOOL_JSON" | jq -c --arg p "$PROJECT" 'if has("project") then . else . + {project:$p} end')"
     RES="$(memory_cli "$TOOL" "$ARGS" 2>/dev/null || true)"
     [[ -n "$RES" ]] || unavailable

package/scripts/tools/graph-snapshot.sh

@@ -73,17 +73,41 @@ command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 2; }
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || { echo "could not index repo — nothing written" >&2; exit 2; }
 
+# ...then ALWAYS re-index. memory_ensure_index calls index_repository only when the
+# project is ABSENT — correct for the graph-*.sh query wrappers, which must stay
+# cheap — so on an already-indexed repo this tool used to write a gate marker with a
+# fresh `generated_at` over a frozen index: a deleted symbol stayed resolvable, a new
+# one never appeared, and nothing in the output said so. Refreshing is this tool's
+# entire job. The engine indexes incrementally, so the repeat call is cheap.
+REFRESHED="$(memory_index_bounded "$REPO_ABS" 2>/dev/null | jq -r '.project // empty' 2>/dev/null || true)"
+[[ -n "$REFRESHED" ]] && PROJECT="$REFRESHED"
+
 mkdir -p "$OUT"
 
 # Prune any stale fat-snapshot artifacts from a prior (pre-engine-only) run so a
 # re-index migrates the repo to the thin model.
-rm -f "$OUT/architecture.json" "$OUT/hotspots.jsonl" \
-      "$OUT/module-deps.mermaid" "$OUT/proto-map.mermaid" 2>/dev/null || true
-rm -rf "$OUT/okf" 2>/dev/null || true
+#
+# Gated on $OUT carrying positive evidence that Draft owns it. --out is
+# caller-supplied and the mkdir -p above will happily create a typo'd path, so an
+# ungated `rm -rf "$OUT/okf"` turns a mistyped flag into data loss. Evidence is
+# the default location, a marker from a previous run, or a prior fat snapshot
+# (which always carried architecture.json / hotspots.jsonl).
+draft_owns_out_dir() {
+    [[ "$OUT" == "$REPO_ABS/draft/graph" ]] && return 0
+    [[ -f "$OUT/schema.yaml" ]] && return 0
+    [[ -f "$OUT/architecture.json" || -f "$OUT/hotspots.jsonl" ]] && return 0
+    return 1
+}
+
+if draft_owns_out_dir; then
+    rm -f "$OUT/architecture.json" "$OUT/hotspots.jsonl" \
+          "$OUT/module-deps.mermaid" "$OUT/proto-map.mermaid" 2>/dev/null || true
+    rm -rf "$OUT/okf" 2>/dev/null || true
+fi
 
 # schema.yaml — provenance + gate. Counts are point-of-index provenance only;
 # the live engine is authoritative.
-STATUS_JSON="$(memory_cli index_status "{\"project\":\"$PROJECT\"}" || echo '{}')"
+STATUS_JSON="$(memory_cli index_status "$(jq -n --arg p "$PROJECT" '{project:$p}')" || echo '{}')"
 # Tolerate field-name variation AND non-JSON output across engine versions;
 # counts are provenance only and must never abort the gate-marker write.
 NODES="$(echo "$STATUS_JSON" | jq -r '.nodes // .node_count // .total_nodes // 0' 2>/dev/null || echo 0)"
@@ -94,7 +118,7 @@ VER="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}' || echo unknown)"
 # incrementally (content-based, git-aware), so re-indexing only touches changed
 # files. detect_changes reports that working-tree delta — recorded as provenance
 # and echoed so a refresh shows what moved. Best-effort: never aborts the write.
-CHANGES_JSON="$(memory_cli detect_changes "{\"project\":\"$PROJECT\"}" 2>/dev/null || echo '{}')"
+CHANGES_JSON="$(memory_cli detect_changes "$(jq -n --arg p "$PROJECT" '{project:$p}')" 2>/dev/null || echo '{}')"
 echo "$CHANGES_JSON" | jq -e . >/dev/null 2>&1 || CHANGES_JSON='{}'
 CHANGED_FILES="$(echo "$CHANGES_JSON" | jq -r '.changed_count // (.changed_files | length?) // 0' 2>/dev/null || echo 0)"
 IMPACTED="$(echo "$CHANGES_JSON" | jq -r '(.impacted_symbols | length?) // 0' 2>/dev/null || echo 0)"

package/scripts/tools/hotspot-rank.sh

@@ -65,7 +65,8 @@ unavailable() { echo '{"hotspots":[],"source":"unavailable"}'; exit 2; }
 
 graph_bootstrap "$REPO" || unavailable
 
-ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"hotspots\"]}" || true)"
+ARCH_JSON="$(memory_cli get_architecture \
+    "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["hotspots"]}')" || true)"
 [[ -n "$ARCH_JSON" ]] || unavailable
 echo "$ARCH_JSON" | jq -e . >/dev/null 2>&1 || unavailable
 

package/scripts/tools/install-smoke-test.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# install-smoke-test.sh
+#
+# Exercises the real first-install path on a throwaway clone.
+#
+# The v2.8.3 install hang was invisible to `make test` because every suite runs
+# against the working tree, and the working tree is never what a new user gets.
+# A new user gets `git clone --depth 1` followed by manifest discovery and a
+# writer pass over an empty HOME. This reproduces exactly that, in that order,
+# so a regression in any of those steps fails a build instead of a user.
+#
+# Requires: git, node 18+. Does NOT require the `claude` CLI and never touches
+# the network — the graph-engine fetch is stubbed out via --no-graph.
+#
+# Usage:
+#   scripts/tools/install-smoke-test.sh                  # clone this repo, run all checks
+#   scripts/tools/install-smoke-test.sh --repo <path>    # smoke-test another checkout
+#   scripts/tools/install-smoke-test.sh --keep           # leave the sandbox for inspection
+#   scripts/tools/install-smoke-test.sh --json
+#
+# Exit codes:
+#   0  install path is healthy
+#   1  a check failed
+#   2  usage / runtime error
+
+set -euo pipefail
+
+usage() {
+    cat <<'EOF'
+install-smoke-test.sh — clean-clone install smoke test
+
+Options:
+  --repo <path>  Repository to clone (default: this repo)
+  --keep         Do not delete the sandbox on exit
+  --json         Emit JSON instead of human-readable output
+  --help, -h     Show this message
+EOF
+}
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+    usage
+    exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+KEEP=0
+EMIT_JSON=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo)
+            [[ -n "${2:-}" ]] || { echo "install-smoke-test: --repo requires a value" >&2; exit 2; }
+            REPO_ROOT="$2"; shift 2 ;;
+        --keep) KEEP=1; shift ;;
+        --json) EMIT_JSON=1; shift ;;
+        --help|-h) usage; exit 0 ;;
+        *) echo "install-smoke-test: unknown argument '$1'" >&2; usage >&2; exit 2 ;;
+    esac
+done
+
+[[ -d "$REPO_ROOT" ]] || { echo "install-smoke-test: no such directory: $REPO_ROOT" >&2; exit 2; }
+command -v git  >/dev/null || { echo "install-smoke-test: git not found" >&2; exit 2; }
+command -v node >/dev/null || { echo "install-smoke-test: node not found" >&2; exit 2; }
+
+SANDBOX="$(mktemp -d "${TMPDIR:-/tmp}/draft-install-smoke.XXXXXX")"
+cleanup() { [[ "$KEEP" -eq 1 ]] || rm -rf "$SANDBOX"; }
+trap cleanup EXIT
+
+CLONE="$SANDBOX/clone"
+FAKE_HOME="$SANDBOX/home"
+PROJECT="$SANDBOX/project"
+mkdir -p "$FAKE_HOME" "$PROJECT"
+
+FAILURES=()
+RESULTS=()
+
+# Collapse a file to one truncated line. Done in-shell rather than with
+# `| cut -c1-200` because an early-closing reader plus `pipefail` turns a
+# harmless truncation into a SIGPIPE failure of the whole script.
+oneline() {
+    local text
+    text="$(tr '\n' ' ' < "$1")"
+    printf '%s' "${text:0:200}"
+}
+
+lastlines() {
+    local text
+    text="$(tail -n "$2" "$1" | tr '\n' ' ')"
+    printf '%s' "${text:0:200}"
+}
+
+record() {
+    local name="$1" ok="$2" detail="${3:-}"
+    RESULTS+=("$name|$ok|$detail")
+    if [[ "$ok" == "true" ]]; then
+        [[ "$EMIT_JSON" -eq 1 ]] || echo " PASS: $name${detail:+ — $detail}"
+    else
+        [[ "$EMIT_JSON" -eq 1 ]] || echo " FAIL: $name${detail:+ — $detail}"
+        FAILURES+=("$name")
+    fi
+}
+
+[[ "$EMIT_JSON" -eq 1 ]] || echo "=== Install smoke test (sandbox: $SANDBOX) ==="
+
+# 1. Shallow clone — the literal first step of `plugin marketplace add`.
+#    file:// forces the real transfer path; a plain local path would hardlink
+#    and hide size problems.
+if git clone --depth 1 --quiet "file://$REPO_ROOT" "$CLONE" 2>"$SANDBOX/clone.err"; then
+    record "shallow clone succeeds" "true"
+else
+    record "shallow clone succeeds" "false" "$(oneline "$SANDBOX/clone.err")"
+fi
+
+if [[ -d "$CLONE" ]]; then
+    clone_mb="$(du -sm "$CLONE" | cut -f1)"
+    record "clone size recorded" "true" "${clone_mb} MB on disk"
+
+    # 2. Manifest discovery — install fails here if plugin.json is malformed or
+    #    points at a skills directory the clone does not contain.
+    if node -e '
+        const fs = require("fs"), path = require("path");
+        const root = process.argv[1];
+        const plugin = JSON.parse(fs.readFileSync(path.join(root, ".claude-plugin/plugin.json"), "utf8"));
+        const market = JSON.parse(fs.readFileSync(path.join(root, ".claude-plugin/marketplace.json"), "utf8"));
+        if (!plugin.name) throw new Error("plugin.json has no name");
+        if (!Array.isArray(market.plugins) || market.plugins.length === 0) throw new Error("marketplace.json lists no plugins");
+        const skills = typeof plugin.skills === "string" ? plugin.skills : "./skills/";
+        const dir = path.join(root, skills);
+        if (!fs.existsSync(dir)) throw new Error("skills dir missing from clone: " + skills);
+        if (fs.readdirSync(dir).length === 0) throw new Error("skills dir is empty in clone");
+    ' "$CLONE" 2>"$SANDBOX/manifest.err"; then
+        record "plugin manifests resolve in the clone" "true"
+    else
+        record "plugin manifests resolve in the clone" "false" "$(oneline "$SANDBOX/manifest.err")"
+    fi
+
+    # 3. Every shipped skill must carry name+description frontmatter, or the
+    #    host silently drops it at discovery time.
+    bad_skills=0
+    skill_count=0
+    while IFS= read -r skill; do
+        skill_count=$((skill_count + 1))
+        head -n 1 "$skill" | grep -q '^---$' || { bad_skills=$((bad_skills + 1)); continue; }
+        fm="$(sed -n '2,/^---$/p' "$skill")"
+        grep -q '^name:' <<< "$fm" || { bad_skills=$((bad_skills + 1)); continue; }
+        grep -q '^description:' <<< "$fm" || bad_skills=$((bad_skills + 1))
+    done < <(find "$CLONE/skills" -name SKILL.md -type f 2>/dev/null | sort)
+
+    if [[ "$skill_count" -eq 0 ]]; then
+        record "shipped skills discoverable" "false" "no SKILL.md files in clone"
+    else
+        record "shipped skills discoverable" \
+            "$([[ "$bad_skills" -eq 0 ]] && echo true || echo false)" \
+            "$skill_count skills, $bad_skills malformed"
+    fi
+
+    # 4. Writer pass against an empty HOME, per host. --dry-run plans every
+    #    write without touching disk; --no-graph keeps it offline.
+    hosts="$(cd "$CLONE" && node -e '
+        const { hosts } = require("./cli/src/hosts");
+        console.log(hosts.map((h) => h.id).join(" "));
+    ' 2>/dev/null || true)"
+
+    if [[ -z "$hosts" ]]; then
+        record "host list enumerable" "false" "cli/src/hosts did not load"
+    else
+        record "host list enumerable" "true" "$hosts"
+        for host in $hosts; do
+            if (cd "$PROJECT" && HOME="$FAKE_HOME" node "$CLONE/cli/bin/draft.js" \
+                    install "$host" --dry-run --no-graph >"$SANDBOX/$host.log" 2>&1); then
+                record "install --dry-run: $host" "true"
+            else
+                record "install --dry-run: $host" "false" "$(lastlines "$SANDBOX/$host.log" 3)"
+            fi
+        done
+        # A dry run that writes is worse than one that fails — it means the real
+        # installer's plan/apply split leaks. Both destinations must be checked:
+        # codex and opencode default to project scope and write AGENTS.md into the
+        # cwd, so a HOME-only assertion misses the likeliest leak.
+        record "dry run left HOME untouched" \
+            "$([[ -z "$(ls -A "$FAKE_HOME")" ]] && echo true || echo false)" \
+            "$(ls -A "$FAKE_HOME" | tr '\n' ' ')"
+        record "dry run left the project dir untouched" \
+            "$([[ -z "$(ls -A "$PROJECT")" ]] && echo true || echo false)" \
+            "$(ls -A "$PROJECT" | tr '\n' ' ')"
+    fi
+
+    # 5. Engine fetcher is present and self-documenting (never invoked here —
+    #    it downloads).
+    if [[ -x "$CLONE/scripts/fetch-memory-engine.sh" ]]; then
+        record "graph engine fetcher shipped and executable" "true"
+    else
+        record "graph engine fetcher shipped and executable" "false" "scripts/fetch-memory-engine.sh missing or not executable"
+    fi
+fi
+
+if [[ "$EMIT_JSON" -eq 1 ]]; then
+    printf '{"sandbox":"%s","failures":%d,"checks":[' "$SANDBOX" "${#FAILURES[@]}"
+    sep=""
+    for r in "${RESULTS[@]}"; do
+        IFS='|' read -r name ok detail <<< "$r"
+        # json_escape (from _lib.sh) also handles backslashes and control chars —
+        # a Windows path or a stack trace in a captured stderr line used to emit
+        # invalid JSON.
+        printf '%s{"name":"%s","ok":%s,"detail":"%s"}' "$sep" "$(json_escape "$name")" "$ok" "$(json_escape "$detail")"
+        sep=","
+    done
+    printf ']}\n'
+else
+    echo ""
+    if [[ "${#FAILURES[@]}" -eq 0 ]]; then
+        echo "Install path healthy — ${#RESULTS[@]} checks passed."
+    else
+        echo "Install path BROKEN — ${#FAILURES[@]} of ${#RESULTS[@]} checks failed:"
+        printf '  - %s\n' "${FAILURES[@]}"
+    fi
+fi
+
+[[ "${#FAILURES[@]}" -eq 0 ]] || exit 1
+exit 0

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

@@ -92,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
@@ -225,7 +220,11 @@ EOF
                 (( BACKUP )) && cp "$path" "$path.bak"
                 # %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" && mv -f "$_tmp" "$path"
+                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

@@ -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-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")