@drafthq/draft 3.6.0 → 3.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"

package/scripts/fetch-memory-engine.sh

@@ -8,7 +8,7 @@
 # which scripts/tools/_lib.sh:find_memory_bin resolves.
 #
 # Pinned by default for reproducibility; override with CMM_VERSION (a tag, e.g.
-# "v0.8.1", or "latest").
+# "v0.9.0", or "latest").
 #
 # Usage:
 #   scripts/fetch-memory-engine.sh [--dest DIR] [--force]
@@ -16,12 +16,18 @@
 # Env:
 #   CMM_VERSION        Release tag to fetch (default: pinned DEFAULT_VERSION).
 #   CMM_DOWNLOAD_URL   Override the release base URL (testing).
+#   DRAFT_STRICT_VERIFY  1 = refuse to install when the checksum cannot be
+#                      verified (missing checksums.txt or unlisted archive).
+#                      Default is warn-and-continue, which keeps installs working
+#                      on releases that ship no checksums file — acceptable for
+#                      individuals, not for anyone who must attest to what runs
+#                      on their machine.
 #
 # Exit codes: 0 installed/already-present, 1 invocation error, 2 fetch/verify failure.
 set -euo pipefail
 
 REPO="DeusData/codebase-memory-mcp"
-DEFAULT_VERSION="v0.8.1"   # pinned; bump deliberately. NOTE: tag must carry the leading "v" AND have published assets (0.7.0 had none → 404).
+DEFAULT_VERSION="v0.9.0"   # pinned; bump deliberately. NOTE: tag must carry the leading "v" AND have published assets (0.7.0 had none → 404).
 VERSION="${CMM_VERSION:-$DEFAULT_VERSION}"
 DEST="$HOME/.cache/draft/bin"
 FORCE=0
@@ -79,7 +85,19 @@ if ! curl -fSL --max-time 300 -o "$TMP/$ARCHIVE" "$BASE/$ARCHIVE"; then
   exit 2
 fi
 
-# --- Verify checksum (best-effort: hard-fail only if the archive is listed) ---
+# --- Verify checksum ---
+# A mismatch is always fatal. An *absent* checksum is fatal only under
+# DRAFT_STRICT_VERIFY=1 — otherwise it warns, so that a release without a
+# checksums.txt does not brick the install for everyone.
+STRICT="${DRAFT_STRICT_VERIFY:-0}"
+unverified() {
+  if [[ "$STRICT" == "1" ]]; then
+    echo "error: $1 (DRAFT_STRICT_VERIFY=1 refuses unverified binaries)" >&2
+    exit 2
+  fi
+  echo "  warning: $1 — skipping verification (set DRAFT_STRICT_VERIFY=1 to make this fatal)" >&2
+}
+
 if curl -fsSL --max-time 60 -o "$TMP/checksums.txt" "$BASE/checksums.txt" 2>/dev/null; then
   expected="$(grep "  $ARCHIVE\$" "$TMP/checksums.txt" 2>/dev/null | awk '{print $1}' | head -1 || true)"
   if [[ -n "$expected" ]]; then
@@ -92,12 +110,12 @@ if curl -fsSL --max-time 60 -o "$TMP/checksums.txt" "$BASE/checksums.txt" 2>/dev
       echo "error: checksum mismatch for $ARCHIVE (expected $expected, got $actual)" >&2
       exit 2
     fi
-    echo "  checksum OK"
+    echo "  checksum OK ($expected)"
   else
-    echo "  warning: $ARCHIVE not found in checksums.txt — skipping verification" >&2
+    unverified "$ARCHIVE not listed in checksums.txt"
   fi
 else
-  echo "  warning: checksums.txt unavailable — skipping verification" >&2
+  unverified "checksums.txt unavailable at $BASE"
 fi
 
 # --- Extract and install ---

package/scripts/lib.sh

@@ -2,21 +2,26 @@
 #
 # Shared validation library for Draft skill files.
 #
-# Sourced by test suites. Defines constants and validation functions
-# but does not execute anything when sourced.
+# Sourced by test suites and the build script. Defines constants and validation
+# functions only — no side effects at source time, shell options included. Every
+# consumer sets its own `set -euo pipefail`; doing it here would silently change
+# the behaviour of whatever sourced us.
 #
 # Usage:
 #   source scripts/lib.sh
 #
 
-set -euo pipefail
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(dirname "$SCRIPT_DIR")"
 SKILLS_DIR="$ROOT_DIR/skills"
 CORE_DIR="$ROOT_DIR/core"
 TOOLS_DIR="$ROOT_DIR/scripts/tools"
 
+# Shared shell helpers (json_escape, apply_dest_mode, …). Side-effect free at
+# source time, so this is safe for every consumer of lib.sh.
+# shellcheck source=tools/_lib.sh
+source "$TOOLS_DIR/_lib.sh"
+
 # ─────────────────────────────────────────────────────────
 # Skill ordering (canonical order for all references)
 # ─────────────────────────────────────────────────────────
@@ -250,6 +255,7 @@ TOOLS=(
     "validate-frontmatter.sh"
     # Foundations hygiene/verification tools
     "check-graph-usage-report.sh"
+    "check-repo-size.sh"
     "check-scope-conflicts.sh"
     "check-skill-line-caps.sh"
     "check-template-noop.sh"
@@ -257,6 +263,7 @@ TOOLS=(
     "diff-templates-vs-tracks.sh"
     "emit-skill-metrics.sh"
     "fix-whitespace.sh"
+    "install-smoke-test.sh"
     "migrate-track-frontmatter.sh"
     "render-track.sh"
     "verify-citations.sh"

package/scripts/tools/_graph_queries.sh

@@ -12,7 +12,10 @@
 #            `STARTS WITH`, `NOT x STARTS WITH`, `AND`, `OR`, relationship-type
 #            alternation `[:A|B]`, simple `count(x)`.
 #   UNSAFE : coalesce(), `<>` / `!=` / `<=` / `>=`, `NOT EXISTS(...)`,
-#            `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern joins.
+#            `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern joins,
+#            and comparing one property against another (`a.x < b.x` — the
+#            parser wants a literal on the right and fails with "expected value
+#            at pos N"). `<` against a literal is fine.
 #            Every builder below stays inside the SAFE set.
 #
 # Label-agnostic on name matches: code units are :Method ⪢ :Function in OO repos;
@@ -43,7 +46,12 @@ gq_q_exists()            { printf "MATCH (f {name:'%s'}) RETURN f.name AS name L
 gq_q_callers()           { printf "MATCH (c)-[:CALLS]->(f {name:'%s'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
 gq_q_callers_prod()      { printf "MATCH (c)-[:CALLS]->(f {name:'%s'}) WHERE c.is_test=false AND NOT c.file_path STARTS WITH 'tests/' RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
 gq_q_callers_qualified() { printf "MATCH (c)-[:CALLS]->(f {qualified_name:'%s'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
-gq_q_cycles2()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(a) WHERE a.qualified_name < b.qualified_name RETURN a.qualified_name AS a, b.qualified_name AS b LIMIT 100"; }
+# The `WHERE a.qualified_name < b.qualified_name` this used to carry was doing
+# two jobs — drop self-loops, and emit each mutual pair once instead of twice —
+# but the engine cannot parse a property-to-property comparison, so the query
+# failed on every call and cycle-detect swallowed the error. Both jobs now happen
+# in jq downstream; the limit is doubled because the raw rows come in pairs.
+gq_q_cycles2()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(a) RETURN a.qualified_name AS a, b.qualified_name AS b LIMIT 200"; }
 gq_q_cycles3()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(c)-[:CALLS]->(a) RETURN a.qualified_name AS a, b.qualified_name AS b, c.qualified_name AS c LIMIT 100"; }
 gq_q_tests()             { printf "MATCH (t)-[:TESTS]->(f {name:'%s'}) RETURN t.qualified_name AS test, t.file_path AS file LIMIT 200" "$1"; }
 gq_q_tested_all()        { printf "MATCH (t)-[:TESTS]->(f) RETURN f.qualified_name AS symbol LIMIT 2000"; }
@@ -53,7 +61,6 @@ gq_q_co_change()         { printf "MATCH (a:File)-[r:FILE_CHANGES_WITH]->(b:File
 gq_q_inherits()          { printf "MATCH (c)-[:INHERITS]->(p) RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 500"; }
 gq_q_inherits_sym()      { printf "MATCH (c)-[:INHERITS]->(p) WHERE c.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
 gq_q_derived_sym()       { printf "MATCH (c)-[:INHERITS]->(p) WHERE p.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
-gq_q_writes()            { printf "MATCH (f {name:'%s'})-[:WRITES]->(v) RETURN v.name AS target, v.file_path AS file LIMIT 200" "$1"; }
 gq_q_raises()            { printf "MATCH (f {name:'%s'})-[:RAISES|THROWS]->(e) RETURN e.name AS error, e.qualified_name AS qualified LIMIT 200" "$1"; }
 gq_q_raisers()           { printf "MATCH (f)-[:RAISES|THROWS]->(e {name:'%s'}) RETURN f.qualified_name AS raiser, f.file_path AS file LIMIT 200" "$1"; }
 gq_q_node_props()        { printf "MATCH (f) RETURN f.qualified_name AS q, f.complexity AS c, f.cognitive AS cog, f.is_entry_point AS ep LIMIT 10000"; }

package/scripts/tools/_lib.sh

@@ -5,6 +5,21 @@
 
 # shellcheck shell=bash
 
+# Give a mktemp-created replacement file the mode its destination should carry.
+# mktemp creates 0600 and `mv` swaps the inode, so an atomic rewrite silently
+# strips the destination's permissions (a 0644 doc came back 0600). Call this on
+# the temp file BEFORE the mv. Uses the destination's current mode when it
+# exists, else the mode a plain `>` redirect would have produced under the
+# caller's umask.
+apply_dest_mode() {
+    local tmp="$1" dest="${2:-}" mode=""
+    if [[ -n "$dest" && -e "$dest" ]]; then
+        mode="$(stat -c '%a' "$dest" 2>/dev/null || stat -f '%Lp' "$dest" 2>/dev/null || true)"
+    fi
+    [[ -n "$mode" ]] || mode="$(printf '%o' "$(( 0666 & ~0$(umask) ))")"
+    chmod "$mode" "$tmp" 2>/dev/null || true
+}
+
 json_escape() {
     local s="$1"
     s="${s//\\/\\\\}"
@@ -15,7 +30,6 @@ json_escape() {
     printf '%s' "$s"
 }
 
-# Extract a top-level YAML frontmatter field value from a Markdown file.
 # Discover track directories under a repo root (default: caller's Draft repo).
 discover_track_dirs() {
     local repo_root="${1:-}"
@@ -90,6 +104,7 @@ skill_line_cap() {
     printf '%s' "$global_cap"
 }
 
+# Extract a top-level YAML frontmatter field value from a Markdown file.
 get_yaml_field() {
     local file="$1"
     local key="$2"
@@ -109,11 +124,6 @@ get_yaml_field() {
     ' "$file"
 }
 
-# Locate the `codebase-memory-mcp` binary (Draft knowledge-graph engine).
-# Sets MEMORY_BIN globally; returns 0 if found, 1 otherwise.
-# Preference: PATH > Draft-managed install (~/.cache/draft/bin) > vendored bin/<arch> under known roots.
-# No legacy fallbacks: the Aether `graph`/`graph-clang` binaries are retired.
-
 # GitHub-flavored-markdown-ish heading id (shared by TOC, anchors, link fixers).
 # Keeps underscores; strips other punctuation; collapses whitespace to '-'.
 gfm_slug() {
@@ -124,7 +134,9 @@ gfm_slug() {
     printf '%s' "$s"
 }
 
-# Count entries in an x-grounded-paths frontmatter field.
+# Count entries in an x-grounded-paths frontmatter field. Always prints an
+# integer — a page with no such field counts 0, not "" (callers embed the value
+# in diagnostics, and an empty string rendered as "x-grounded-paths  < 2").
 # Supports both inline (`x-grounded-paths: ["a", "b"]`) and block lists:
 #   x-grounded-paths:
 #     - "a"
@@ -140,20 +152,26 @@ grounded_paths_count() {
             sub(/^x-grounded-paths:[[:space:]]*\[/, "", line)
             sub(/\].*$/, "", line)
             gsub(/[[:space:]]/, "", line)
-            if (line=="") { print 0; exit }
+            if (line=="") { print 0; printed=1; exit }
             n=split(line, a, ",")
             print n
+            printed=1
             exit
         }
         fm && /^x-grounded-paths:[[:space:]]*$/ { collect=1; next }
         fm && collect {
             if ($0 ~ /^[[:space:]]*-[[:space:]]*/) { n++; next }
-            if ($0 ~ /^[A-Za-z0-9_-]+:/) { print n+0; exit }
+            if ($0 ~ /^[A-Za-z0-9_-]+:/) { print n+0; printed=1; exit }
         }
-        END { if (collect) print n+0 }
+        END { if (!printed) print n+0 }
     ' "$file"
 }
 
+# Locate the `codebase-memory-mcp` binary (Draft knowledge-graph engine).
+# Sets MEMORY_BIN globally; returns 0 if found, 1 otherwise.
+# Precedence: DRAFT_MEMORY_DISABLE (hard off) > DRAFT_MEMORY_BIN > PATH >
+# Draft-managed install (~/.cache/draft/bin) > vendored bin/<arch> under known roots.
+# No legacy fallbacks: the Aether `graph`/`graph-clang` binaries are retired.
 find_memory_bin() {
     local repo_abs="$1"
     local self_repo="$2"
@@ -298,7 +316,11 @@ _can_cgroup_bound() {
 # Echoes the engine's JSON result on stdout (same contract as memory_cli).
 memory_index_bounded() {
     local repo_abs="$1"
-    local json="{\"repo_path\":\"$repo_abs\"}"
+    # Payload built with jq (never string concatenation) so a repo path
+    # containing a `"` or `\` can never corrupt the JSON sent to the engine.
+    command -v jq >/dev/null 2>&1 || return 1
+    local json
+    json="$(jq -n --arg r "$repo_abs" '{repo_path:$r}')" || return 1
     export CBM_WORKERS="${CBM_WORKERS:-4}"
     local total pct
     total="$(_total_ram_mb)"

package/scripts/tools/check-repo-size.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# check-repo-size.sh
+#
+# Guards the size of the tree at HEAD.
+#
+# `claude plugin marketplace add <owner>/<repo>` git-clones this repository, so
+# every byte tracked at HEAD is downloaded before the plugin can be installed.
+# In v2.8.3 ~670 MB of audiobook .m4a files in HEAD stalled that first install
+# step with no error message — an install-breaking regression that no test
+# caught. This is that test.
+#
+# The threshold is deliberately loose (default 10 MB against a ~6 MB HEAD): it
+# exists to catch binary assets landing in HEAD, not to police prose growth.
+#
+# Usage:
+#   scripts/tools/check-repo-size.sh                 # default cap, human output
+#   scripts/tools/check-repo-size.sh --max-mb 5      # custom cap
+#   scripts/tools/check-repo-size.sh --json          # machine-readable
+#   scripts/tools/check-repo-size.sh --rev v3.6.0    # audit a past revision
+#
+# Exit codes:
+#   0  tree at HEAD is within the cap
+#   1  cap exceeded
+#   2  usage / runtime error
+
+set -euo pipefail
+
+usage() {
+    cat <<'EOF'
+check-repo-size.sh — fail if the tree at HEAD exceeds a size cap
+
+Options:
+  --max-mb <n>   Cap in megabytes (default: 10)
+  --rev <rev>    Revision to measure (default: HEAD)
+  --repo <path>  Repository root (default: this repo)
+  --top <n>      Largest blobs to list (default: 10)
+  --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)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+MAX_MB=10
+REV="HEAD"
+TOP=10
+EMIT_JSON=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --max-mb)
+            [[ -n "${2:-}" ]] || { echo "check-repo-size: --max-mb requires a value" >&2; exit 2; }
+            MAX_MB="$2"; shift 2 ;;
+        --rev)
+            [[ -n "${2:-}" ]] || { echo "check-repo-size: --rev requires a value" >&2; exit 2; }
+            REV="$2"; shift 2 ;;
+        --repo)
+            [[ -n "${2:-}" ]] || { echo "check-repo-size: --repo requires a value" >&2; exit 2; }
+            REPO_ROOT="$2"; shift 2 ;;
+        --top)
+            [[ -n "${2:-}" ]] || { echo "check-repo-size: --top requires a value" >&2; exit 2; }
+            TOP="$2"; shift 2 ;;
+        --json) EMIT_JSON=1; shift ;;
+        --help|-h) usage; exit 0 ;;
+        *) echo "check-repo-size: unknown argument '$1'" >&2; usage >&2; exit 2 ;;
+    esac
+done
+
+[[ "$MAX_MB" =~ ^[0-9]+$ ]] || { echo "check-repo-size: --max-mb must be an integer, got '$MAX_MB'" >&2; exit 2; }
+[[ "$TOP" =~ ^[0-9]+$ ]]    || { echo "check-repo-size: --top must be an integer, got '$TOP'" >&2; exit 2; }
+[[ -d "$REPO_ROOT" ]]       || { echo "check-repo-size: no such directory: $REPO_ROOT" >&2; exit 2; }
+
+cd "$REPO_ROOT"
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "check-repo-size: $REPO_ROOT is not a git repository" >&2; exit 2; }
+git rev-parse --verify --quiet "$REV" >/dev/null || { echo "check-repo-size: unknown revision '$REV'" >&2; exit 2; }
+
+# `ls-tree -l` gives per-blob sizes; symlinks/submodules report '-' and are skipped.
+listing="$(git ls-tree -r -l "$REV")"
+
+total_bytes=0
+file_count=0
+while read -r _mode _type _sha size _path; do
+    [[ "$size" =~ ^[0-9]+$ ]] || continue
+    total_bytes=$((total_bytes + size))
+    file_count=$((file_count + 1))
+done <<< "$listing"
+
+max_bytes=$((MAX_MB * 1024 * 1024))
+status="ok"
+[[ "$total_bytes" -gt "$max_bytes" ]] && status="over"
+
+total_mb="$(awk -v b="$total_bytes" 'BEGIN { printf "%.2f", b / 1048576 }')"
+
+if [[ "$EMIT_JSON" -eq 1 ]]; then
+    printf '{"rev":"%s","status":"%s","total_bytes":%d,"total_mb":%s,"max_mb":%d,"files":%d}\n' \
+        "$REV" "$status" "$total_bytes" "$total_mb" "$MAX_MB" "$file_count"
+else
+    echo "Tree at $REV: ${total_mb} MB across $file_count files (cap: ${MAX_MB} MB)"
+    if [[ "$status" == "over" ]]; then
+        echo ""
+        echo "Largest tracked blobs:"
+        # Materialize the sorted list before slicing it. Piping straight into
+        # `head` lets head close the pipe early, which under `pipefail` surfaces
+        # sort's SIGPIPE as a hard failure — non-deterministically, depending on
+        # whether the output fit in the pipe buffer.
+        largest="$(awk '$4 ~ /^[0-9]+$/ { printf "  %8.2f MB  %s\n", $4 / 1048576, $5 }' <<< "$listing" | sort -rn)"
+        head -n "$TOP" <<< "$largest"
+    fi
+fi
+
+if [[ "$status" == "over" ]]; then
+    echo "" >&2
+    echo "FAIL: HEAD exceeds ${MAX_MB} MB. 'plugin marketplace add' clones this tree —" >&2
+    echo "      oversized blobs stall install with no error. Ship large assets as" >&2
+    echo "      GitHub Release attachments instead of committing them." >&2
+    exit 1
+fi
+
+exit 0

package/scripts/tools/check-skill-line-caps.sh

@@ -64,7 +64,6 @@ declare -a findings=()
 record() { findings+=("$1|$2|$3"); over_count=$((over_count + 1)); }
 
 while IFS= read -r path; do
-    rel="${path#"$REPO_ROOT/"}"
     name="$(basename "$(dirname "$path")")"
     lines="$(wc -l < "$path" | tr -d ' ')"
     cap="$(skill_line_cap "$name" "$CAPS_CONF" "$GLOBAL_CAP")"
@@ -90,7 +89,7 @@ emit() {
             printf 'OK: all skills within cap (default %d).\n' "$GLOBAL_CAP"
             return
         fi
-        local mode="warn-only" stream=stderr
+        local mode="warn-only"
         ((ENFORCE)) && mode="enforced"
         if ((ENFORCE)); then
             printf 'SKILL-CAPS: %d skill(s) over cap (%s):\n' \

package/scripts/tools/check-template-noop.sh

@@ -51,7 +51,6 @@ while IFS= read -r f; do
     [[ -z "$f" ]] && continue
     case "$f" in
         skills/*|scripts/tools/*)
-            # Skip changes to the templates themselves living under scripts.
             touches_skills_or_tools=1 ;;
         core/templates/*)
             touches_templates=1 ;;

package/scripts/tools/classify-files.sh

@@ -34,8 +34,8 @@ Output (per file): {path, lang, category, is_test, is_generated, loc, module}
 
 Language is inferred from extension and shebang. A file is classified as a
 test when its path or basename matches common test patterns. It is flagged
-generated when the first 5 lines contain "Code generated" or "DO NOT EDIT".
-Module is the first path segment under root.
+generated when the first 5 lines contain "Code generated", "DO NOT EDIT",
+"@generated", or "autogenerated". Module is the first path segment under root.
 EOF
 }
 

package/scripts/tools/cycle-detect.sh

@@ -58,18 +58,26 @@ graph_bootstrap "$REPO" || unavailable
 # 2- and 3-node CALLS cycles. Cypher lives in _graph_queries.sh (label-agnostic;
 # the Phase 0 fix — code units are mostly :Method, and CALLS only connects
 # callables). LIMIT 100 caps each, so results are a sample, not exhaustive.
-R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)" || echo '{}')"
-R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)" || echo '{}')"
-
-# Guard against empty/non-JSON engine output so --argjson never aborts the script.
-echo "$R2" | jq -e . >/dev/null 2>&1 || R2='{}'
-echo "$R3" | jq -e . >/dev/null 2>&1 || R3='{}'
+#
+# A failed query is not an empty result. Substituting `{}` and carrying on
+# reported `source:"memory-graph"` with zero cycles — a clean bill of health
+# derived from a query that never ran, which is exactly the true-negative
+# confusion Guardrail 4 exists to prevent, and the one failure mode a caller
+# cannot detect. Both queries must land for the sample to mean anything, so
+# either failure routes to `unavailable`. gq_run only ever echoes validated
+# JSON, so nothing downstream needs a second shape guard.
+R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)")" || unavailable
+R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)")" || unavailable
 
+# Self-loops and duplicate orderings are filtered here rather than in Cypher:
+# the engine rejects `a.x < b.x`, which is what the query used to rely on.
+# A 2-cycle comes back twice (A,B and B,A), hence the doubled LIMIT upstream.
 jq -n --argjson r2 "$R2" --argjson r3 "$R3" '
-    ( ((($r2.rows) // []) | length) >= 100
+    ( ((($r2.rows) // []) | length) >= 200
       or ((($r3.rows) // []) | length) >= 100 ) as $trunc
+    | ( ($r2.rows // []) | map(select(.[0] != .[1])) | unique_by(sort) ) as $two
     | {
-        cycles: (((($r2.rows) // []) + (($r3.rows) // []))),
+        cycles: ($two + ($r3.rows // [])),
         truncated: $trunc,
         source: "memory-graph"
       }'

package/scripts/tools/fix-whitespace.sh

@@ -83,6 +83,9 @@ fix_file() {
         return 1 # already clean — no change on disk
     fi
 
+    # mktemp creates 0600 and `mv` swaps the inode — carry the destination's mode
+    # across, or an atomic rewrite silently strips the file's permissions.
+    apply_dest_mode "$_tmp" "$file"
     mv -f "$_tmp" "$file"
     return 0
 }

package/scripts/tools/git-metadata.sh

@@ -127,6 +127,8 @@ if (( WRITE_PROJECT_METADATA )); then
     fi
     CMD="${GENERATED_BY:-draft:init}"
     _tmp="$(mktemp "${META_FILE}.XXXXXX")"
+    # errexit on a failed write would otherwise leave metadata.json.XXXXXX behind.
+    trap 'rm -f "$_tmp"' EXIT
     cat > "$_tmp" <<EOF
 {
   "\$schema": "Draft Project Metadata Schema",
@@ -150,7 +152,11 @@ if (( WRITE_PROJECT_METADATA )); then
   "synced_to_commit": "$FULL_SHA"
 }
 EOF
+    # mktemp creates 0600 and `mv` swaps the inode — carry the destination's mode
+    # across, or an atomic rewrite silently strips the file's permissions.
+    apply_dest_mode "$_tmp" "$META_FILE"
     mv -f "$_tmp" "$META_FILE"
+    trap - EXIT
     echo "Written: $META_FILE (synced_to_commit=$FULL_SHA)"
     exit 0
 fi

package/scripts/tools/graph-arch.sh

@@ -57,7 +57,7 @@ unavailable() { echo '{"source":"unavailable"}'; exit 2; }
 
 graph_bootstrap "$REPO" || unavailable
 
-ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"all\"]}" || true)"
+ARCH_JSON="$(memory_cli get_architecture "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["all"]}')" || true)"
 [[ -n "$ARCH_JSON" ]] || unavailable
 
 # Validate it parses and looks like an architecture object before emitting.

package/scripts/tools/graph-callers.sh

@@ -9,7 +9,10 @@
 #   scripts/tools/graph-callers.sh --repo DIR --symbol NAME
 #                                  [--transitive[=N]] [--prod-only] [--qualified]
 #
-# Output: JSON {symbol, callers:[{name,file[,hop]}], status, source}.
+# Output: JSON {symbol, callers:[{name,file,qualified[,hop]}], status, source}.
+#   `file` is always a path (empty when the engine does not carry one — the
+#   trace_path expander behind --transitive returns no file_path); the symbol's
+#   qualified name is in `qualified`, never smuggled into `file`.
 #   source = "memory-graph" | "unavailable"
 #   status = "ok" | "no-edges" | "no-match" | "unavailable"
 #            (fail-loud: distinguishes node-not-found from node-has-no-callers
@@ -92,7 +95,7 @@ if [[ "$TRANSITIVE" -eq 1 ]]; then
     fi
     echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
         {symbol:$s,
-         callers: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         callers: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
          status:$st, source:"memory-graph"}'
     exit 0
 fi
@@ -113,5 +116,5 @@ STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
 
 echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
     {symbol:$s,
-     callers: [ (.rows // [])[] | {name:.[0], file:.[1]} ],
+     callers: [ (.rows // [])[] | {name:.[0], file:(.[1] // ""), qualified:""} ],
      status:$st, source:"memory-graph"}'

package/scripts/tools/graph-impact.sh

@@ -9,7 +9,9 @@
 # Usage:
 #   scripts/tools/graph-impact.sh --repo DIR (--file PATH | --symbol NAME) [--depth N]
 #
-# Output: JSON {target, kind, impacted:[{name,file,hop}], source}.
+# Output: JSON {target, kind, impacted:[{name,file,qualified,hop}], source}.
+#   `file` is always a path (empty when the engine carries none); the qualified
+#   name has its own field rather than being emitted as if it were a path.
 #   source = "memory-graph" | "unavailable"
 #
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
@@ -78,7 +80,7 @@ if [[ -n "$SYMBOL" ]]; then
     echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
     echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"symbol",
-         impacted: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         impacted: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
          source:"memory-graph"}'
 else
     # File impact: detect_changes maps the working-tree diff to impacted symbols.

package/scripts/tools/graph-init.sh

@@ -93,7 +93,7 @@ ensure_engine() {
 engine_unavailable() {
     if [[ "$EMIT_JSON" -eq 1 ]]; then
         printf '{"status":"unavailable","root":"%s","scope":"%s","is_root":%s}\n' \
-            "$ROOT_ABS" "$SCOPE_ABS" "$IS_ROOT"
+            "$(json_escape "$ROOT_ABS")" "$(json_escape "$SCOPE_ABS")" "$IS_ROOT"
     else
         echo "WARNING: knowledge-graph engine (codebase-memory-mcp) is unavailable — no graph built." >&2
         echo "  The engine is Draft's default capability tier. Install it with:" >&2
@@ -115,7 +115,7 @@ build_snapshot() {
 # Path from <module>/draft/graph back to <root>/draft/graph (module is under root).
 root_link_relpath() {
     local sub="${SCOPE_ABS#"$ROOT_ABS"/}"
-    local ups=2 seg
+    local ups seg
     IFS='/' read -ra seg <<< "$sub"
     ups=$(( ${#seg[@]} + 2 ))
     local i out=""
@@ -135,13 +135,16 @@ write_root_link() {
     fi
     root_commit="$(git -C "$ROOT_ABS" rev-parse --verify --quiet HEAD 2>/dev/null || echo none)"
     ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    # Every interpolated value goes through json_escape: a repo path or engine
+    # project name carrying a quote or backslash would otherwise emit a
+    # root-link.json that no consumer can parse.
     cat > "$mod_graph/root-link.json" <<EOF
 {
-  "root_graph": "$rel",
-  "root_abs": "$ROOT_ABS/draft/graph",
-  "root_project": "${root_project:-unknown}",
-  "root_commit": "$root_commit",
-  "status": "$status",
+  "root_graph": "$(json_escape "$rel")",
+  "root_abs": "$(json_escape "$ROOT_ABS/draft/graph")",
+  "root_project": "$(json_escape "${root_project:-unknown}")",
+  "root_commit": "$(json_escape "$root_commit")",
+  "status": "$(json_escape "$status")",
   "linked_at": "$ts",
   "linked_by": "graph-init.sh",
   "note": "Root is the authoritative whole-repo graph. Follow root_graph for cross-module understanding."
@@ -173,7 +176,8 @@ fi
 
 if [[ "$EMIT_JSON" -eq 1 ]]; then
     printf '{"status":"ok","root":"%s","scope":"%s","is_root":%s,"root_built":%s,"module_built":%s,"link_status":"%s"}\n' \
-        "$ROOT_ABS" "$SCOPE_ABS" "$IS_ROOT" "$ROOT_BUILT" "$MODULE_BUILT" "$LINK_STATUS"
+        "$(json_escape "$ROOT_ABS")" "$(json_escape "$SCOPE_ABS")" \
+        "$IS_ROOT" "$ROOT_BUILT" "$MODULE_BUILT" "$(json_escape "$LINK_STATUS")"
 else
     echo "--- graph-init ---"
     echo "Root:  $ROOT_ABS$([[ $IS_ROOT -eq 1 ]] && echo '  (this scope is the root)')"

package/scripts/tools/graph-preflight.sh

@@ -168,7 +168,10 @@ if find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
   ENGINE_FOUND=true
   VER="$("$ENGINE" --version 2>/dev/null | head -1 || echo '?')"
   ok "Engine: $ENGINE ($VER)"
+  # Numeric-only: the value is emitted bare into the --json report, so a
+  # non-numeric field (engine output format drift) would produce invalid JSON.
   LIMIT="$("$ENGINE" config list 2>/dev/null | awk '/auto_index_limit/{print $3}' || true)"
+  [[ "$LIMIT" =~ ^[0-9]+$ ]] || LIMIT=""
   [[ -n "$LIMIT" ]] && info "auto_index_limit: $LIMIT (governs AUTO-index only; explicit index_repository should bypass)" || true
   if [[ "$GIT_OK" -eq 1 && "${LIMIT:-}" =~ ^[0-9]+$ && "$TRACKED" -gt "$LIMIT" ]]; then
     warn "Tracked files ($TRACKED) > auto_index_limit ($LIMIT) — confirm the explicit index isn't truncated near $LIMIT."