@drafthq/draft 3.5.3 → 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,
@@ -59,10 +62,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --cypher) CYPHER="$2"; shift 2;;
-        --tool) TOOL="$2"; shift 2;;
-        --json) TOOL_JSON="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --cypher) CYPHER="${2:?--cypher requires a value}"; shift 2;;
+        --tool) TOOL="${2:?--tool requires a value}"; shift 2;;
+        --json) TOOL_JSON="${2:?--json requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -89,25 +92,79 @@ 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
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+# --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; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 if [[ -n "$CYPHER" ]]; then
     RES="$(gq_run "$PROJECT" "$CYPHER" || true)"
@@ -115,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-risk.sh

@@ -42,8 +42,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --min-complexity) MIN_COMPLEXITY="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --min-complexity) MIN_COMPLEXITY="${2:?--min-complexity requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -52,16 +52,9 @@ done
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ "$MIN_COMPLEXITY" =~ ^[0-9]+$ ]] || { echo "ERROR: --min-complexity must be a non-negative integer" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"risky":[],"total":0,"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 RES="$(gq_run "$PROJECT" "$(gq_q_risk)" || true)"
 [[ -n "$RES" ]] || unavailable

package/scripts/tools/graph-search.sh

@@ -40,9 +40,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --query) QUERY="$2"; shift 2;;
-        --limit) LIMIT="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --query) QUERY="${2:?--query requires a value}"; shift 2;;
+        --limit) LIMIT="${2:?--limit requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -52,20 +52,13 @@ done
 [[ -n "$QUERY" ]] || { echo "ERROR: --query is required" >&2; usage >&2; exit 1; }
 [[ "$LIMIT" =~ ^[0-9]+$ ]] || { echo "ERROR: --limit must be a non-negative integer" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     jq -n --arg q "$QUERY" '{query:$q, results:[], source:"unavailable"}' 2>/dev/null \
         || echo '{"results":[],"source":"unavailable"}'
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QUERY" --argjson n "$LIMIT" \
     '{project:$p, query:$q, limit:$n}')"

package/scripts/tools/graph-snapshot.sh

@@ -52,8 +52,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --out) OUT_DIR="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --out) OUT_DIR="${2:?--out requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -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,11 +118,16 @@ 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)"
 
+# YAML double-quoted scalars: escape backslashes then quotes so an unusual
+# project name or engine version string can never corrupt the marker.
+PROJECT_Y="${PROJECT//\\/\\\\}"; PROJECT_Y="${PROJECT_Y//\"/\\\"}"
+VER_Y="${VER//\\/\\\\}"; VER_Y="${VER_Y//\"/\\\"}"
+
 cat > "$OUT/schema.yaml" <<EOF
 # Draft graph gate marker — written by scripts/tools/graph-snapshot.sh
 # Draft is engine-only: this file carries NO graph data. Its presence signals that
@@ -106,8 +135,8 @@ cat > "$OUT/schema.yaml" <<EOF
 # live via the graph-*.sh wrappers (or \`codebase-memory-mcp cli <tool>\`).
 # Counts below are point-of-index provenance; the live engine is authoritative.
 engine: codebase-memory-mcp
-engine_version: "$VER"
-project: "$PROJECT"
+engine_version: "$VER_Y"
+project: "$PROJECT_Y"
 generated_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 indexed_nodes: $NODES
 indexed_edges: $EDGES

package/scripts/tools/graph-snippet.sh

@@ -44,8 +44,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --qualified|--symbol) QNAME="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --qualified|--symbol) QNAME="${2:?--qualified|--symbol requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -54,20 +54,13 @@ done
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$QNAME" ]] || { echo "ERROR: --qualified is required" >&2; usage >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     jq -n --arg q "$QNAME" '{qualified_name:$q, status:"unavailable", source:"unavailable"}' 2>/dev/null \
         || echo '{"status":"unavailable","source":"unavailable"}'
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QNAME" '{project:$p, qualified_name:$q}')"
 RES="$(memory_cli get_code_snippet "$ARGS" 2>/dev/null || true)"

package/scripts/tools/graph-tests.sh

@@ -48,8 +48,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
         --untested) UNTESTED=1; shift;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -59,9 +59,6 @@ done
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$SYMBOL" || "$UNTESTED" -eq 1 ]] || { echo "ERROR: provide --symbol or --untested" >&2; usage >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     if [[ "$UNTESTED" -eq 1 ]]; then
         echo '{"untested":[],"total":0,"source":"unavailable"}'
@@ -72,11 +69,7 @@ unavailable() {
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 if [[ "$UNTESTED" -eq 1 ]]; then
     EXP="$(gq_run "$PROJECT" "$(gq_q_exported)" || true)"

package/scripts/tools/graph-traces.sh

@@ -49,8 +49,8 @@ EOF
 while [[ $# -gt 0 ]]; do
     case "$1" in
         ingest) ACTION="ingest"; shift;;
-        --repo) REPO="$2"; shift 2;;
-        --file) FILE="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --file) FILE="${2:?--file requires a value}"; shift 2;;
         --experimental) EXPERIMENTAL=1; shift;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown argument: $1" >&2; usage >&2; exit 1;;
@@ -63,19 +63,12 @@ done
 [[ -n "$FILE" ]] || { echo "ERROR: --file is required" >&2; usage >&2; exit 1; }
 [[ -f "$FILE" ]] || { echo "ERROR: --file '$FILE' does not exist" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 jq -e . "$FILE" >/dev/null 2>&1 || { echo "ERROR: --file is not valid JSON" >&2; exit 1; }
 
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
-
 ARGS="$(jq -n --arg p "$PROJECT" --slurpfile t "$FILE" '{project:$p, traces:($t[0])}')"
 RES="$(memory_cli ingest_traces "$ARGS" 2>/dev/null || true)"
 [[ -n "$RES" ]] || unavailable

package/scripts/tools/hotspot-rank.sh

@@ -47,8 +47,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --top) TOP="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --top) TOP="${2:?--top requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -61,18 +61,12 @@ if [[ ! -d "$REPO" ]]; then
     exit 1
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"hotspots":[],"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+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
 
@@ -87,7 +81,7 @@ 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" '
-    (($props[0].rows) // []) as $prows
+    ((($props[0].rows) // []) | map(select(.[0] != null))) as $prows
     | (reduce $prows[] as $r ({};
           .[$r[0]] = {c:((($r[1]) // "0") | tonumber? // 0),
                       cog:((($r[2]) // "0") | tonumber? // 0),

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