@drafthq/draft 3.6.0 → 3.7.2

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,13 +65,26 @@ 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
 
 # Pre-computed complexity/cognitive/is_entry_point per symbol (merged onto fan-in).
-PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props)" || echo '{"rows":[]}')"
-echo "$PROPS_JSON" | jq -e . >/dev/null 2>&1 || PROPS_JSON='{"rows":[]}'
+#
+# The hotspots themselves come from get_architecture above, which is fail-loud,
+# so a failure here costs enrichment rather than the whole result — worth keeping
+# the ranking for. But it must not pass silently: substituting an empty row set
+# gave every symbol complexity 0 and cognitive 0, folded those zeros into `score`,
+# and still reported source:"memory-graph", so a fan-in-only ranking was
+# indistinguishable from a fully measured one. Record the outcome instead, and
+# omit the fields rather than emitting measurements that were never taken.
+if PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props)")"; then
+    ENRICHMENT="ok"
+else
+    PROPS_JSON='{"rows":[]}'
+    ENRICHMENT="unavailable"
+fi
 
 # Merge via temp files (the props row set can exceed argv limits on large repos).
 TMP_ARCH="$(mktemp)"; TMP_PROPS="$(mktemp)"
@@ -79,7 +92,8 @@ trap 'rm -f "$TMP_ARCH" "$TMP_PROPS"' EXIT
 printf '%s' "$ARCH_JSON" > "$TMP_ARCH"
 printf '%s' "$PROPS_JSON" > "$TMP_PROPS"
 
-jq -n --slurpfile arch "$TMP_ARCH" --slurpfile props "$TMP_PROPS" --argjson top "$TOP" '
+jq -n --slurpfile arch "$TMP_ARCH" --slurpfile props "$TMP_PROPS" --argjson top "$TOP" \
+      --arg enrichment "$ENRICHMENT" '
     ((($props[0].rows) // []) | map(select(.[0] != null))) as $prows
     | (reduce $prows[] as $r ({};
           .[$r[0]] = {c:((($r[1]) // "0") | tonumber? // 0),
@@ -88,10 +102,11 @@ jq -n --slurpfile arch "$TMP_ARCH" --slurpfile props "$TMP_PROPS" --argjson top
     | [ (($arch[0].hotspots) // [])[]
         | (.qualified_name) as $q
         | ($pmap[$q] // {c:0, cog:0, ep:false}) as $p
-        | {id:$q, name:.name, fanIn:(.fan_in // 0),
-           complexity:$p.c, cognitive:$p.cog,
-           score:((.fan_in // 0) + $p.c + $p.cog),
-           isEntryPoint:$p.ep} ]
+        | ({id:$q, name:.name, fanIn:(.fan_in // 0),
+            score:((.fan_in // 0) + $p.c + $p.cog)}
+           + (if $enrichment == "ok"
+              then {complexity:$p.c, cognitive:$p.cog, isEntryPoint:$p.ep}
+              else {} end)) ]
     | sort_by(-.score)
     | (if $top > 0 then .[0:$top] else . end) as $h
-    | {hotspots:$h, source:"memory-graph"}'
+    | {hotspots:$h, enrichment:$enrichment, source:"memory-graph"}'

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

@@ -57,25 +57,39 @@ if [[ ! -d "$REPO" ]]; then
     exit 1
 fi
 
+# $1: "unavailable" (engine/query failed) or "empty" (query ran, no such edges).
+# Swallowing a failed query with `{}` used to make both look identical, so an
+# engine failure and a repo with genuinely no cross-file imports produced the
+# same "graph not built" diagram — the reader could not tell which they had.
 stub() {
-    cat <<'EOF'
+    if [[ "${1:-unavailable}" == "empty" ]]; then
+        cat <<'EOF'
+```mermaid
+%% graph is built, but holds no edges of this kind — nothing to draw
+flowchart LR
+    empty["no edges"]
+```
+EOF
+    else
+        cat <<'EOF'
 ```mermaid
 %% graph data unavailable — index the repo with the graph engine first
 flowchart LR
     empty["graph not built"]
 ```
 EOF
+    fi
     exit 2
 }
 
-graph_bootstrap "$REPO" || stub
+graph_bootstrap "$REPO" || stub unavailable
 
 # 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
 # edges for readability.
 render_module_deps() {
-    local res; res="$(gq_run "$PROJECT" "$(gq_q_imports)" || echo '{}')"
-    local edges; edges="$(echo "${res:-{\}}" | jq -r '
+    local res; res="$(gq_run "$PROJECT" "$(gq_q_imports)")" || return 2
+    local edges; edges="$(echo "$res" | jq -r '
         [ (.rows // [])[] | {s:(.[0]|tostring), d:(.[1]|tostring)}
           | select(.s != "" and .d != "" and .s != .d) ]
         | unique | .[0:40][] | "    \"" + .s + "\" --> \"" + .d + "\""' 2>/dev/null || true)"
@@ -85,22 +99,25 @@ render_module_deps() {
 
 # co-change: FILE_CHANGES_WITH coupling (the prior module-deps proxy).
 render_co_change() {
-    local res; res="$(gq_run "$PROJECT" "$(gq_q_co_change)" || echo '{}')"
-    local edges; edges="$(echo "${res:-{\}}" | jq -r '(.rows // [])[] | "    \"" + (.[0]|tostring) + "\" --> \"" + (.[1]|tostring) + "\""' 2>/dev/null || true)"
+    local res; res="$(gq_run "$PROJECT" "$(gq_q_co_change)")" || return 2
+    local edges; edges="$(echo "$res" | jq -r '(.rows // [])[] | "    \"" + (.[0]|tostring) + "\" --> \"" + (.[1]|tostring) + "\""' 2>/dev/null || true)"
     if [[ -z "$edges" ]]; then return 1; fi
     printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"
 }
 
 render_proto_map() {
-    local res; res="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"routes\"]}" || echo '{}')"
-    local edges; edges="$(echo "${res:-{\}}" | jq -r '(.routes // [])[] | "    \"" + ((.method // "")|tostring) + " " + ((.path // "")|tostring) + "\" --> \"" + ((.handler // "?")|tostring) + "\""' 2>/dev/null || true)"
+    local res; res="$(memory_cli get_architecture \
+        "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["routes"]}')" || true)"
+    [[ -n "$res" ]] && echo "$res" | jq -e . >/dev/null 2>&1 || return 2
+    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"
 }
 
+# rc 2 = the query failed; rc 1 = it ran and returned nothing. Different stubs.
 case "$DIAGRAM" in
-    module-deps) render_module_deps || stub ;;
-    co-change)   render_co_change || stub ;;
-    proto-map)   render_proto_map || stub ;;
+    module-deps) render_module_deps || { rc=$?; [[ $rc -eq 1 ]] && stub empty || stub unavailable; } ;;
+    co-change)   render_co_change   || { rc=$?; [[ $rc -eq 1 ]] && stub empty || stub unavailable; } ;;
+    proto-map)   render_proto_map   || { rc=$?; [[ $rc -eq 1 ]] && stub empty || stub unavailable; } ;;
     *) echo "Unknown --diagram '$DIAGRAM' (expected module-deps|co-change|proto-map)" >&2; exit 1 ;;
 esac

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