@drafthq/draft 3.5.3 → 3.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.5.3",
+  "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,17 +16,23 @@
 # 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
 
-usage() { sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; }
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; }
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -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)
 # ─────────────────────────────────────────────────────────
@@ -57,6 +62,76 @@ SKILL_ORDER=(
     assist-review
 )
 
+# ─────────────────────────────────────────────────────────
+# Skill metadata: one row per skill — "<name>|<display header>|<copilot trigger>"
+# The name and header never contain "|"; the trigger may (e.g. "[file|pr N]"),
+# so lookups split on the FIRST TWO pipes only. Coverage against SKILL_ORDER is
+# enforced by tests/test-trigger-functions.sh.
+# ─────────────────────────────────────────────────────────
+
+SKILL_META=(
+    'draft|Draft Overview|"help" or "draft"'
+    'init|Init Command|"init draft", "build the code graph", or "draft init [refresh] [--graph-only] [--module-only]"'
+    'graph|Graph Command|"build graph", "refresh graph", or "draft graph [path]"'
+    'new-track|New Track Command|"new feature" or "draft new-track <description>"'
+    'decompose|Decompose Command|"break into modules" or "draft decompose"'
+    'implement|Implement Command|"implement" or "draft implement"'
+    'coverage|Coverage Command|"check coverage" or "draft coverage"'
+    'deploy-checklist|Deploy Checklist Command|"deploy checklist" or "draft deploy-checklist [track <id>]"'
+    'bughunt|Bug Hunt Command|"hunt bugs" or "draft bughunt [--track <id>]"'
+    'review|Review Command|"review code" or "draft review [--track <id>] [--full]"'
+    'upload|Upload Command|"upload for review" or "draft upload [track <id>]"'
+    'plan|Plan Router|"plan feature" or "draft plan <intent>" (new-track, decompose, adr, tech-debt, change)'
+    'ops|Ops Router|"ops deploy" or "draft ops <intent>" (deploy-checklist, incident, standup, status, revert)'
+    'docs|Docs Router|"write docs" or "draft docs <intent>" (documentation)'
+    'discover|Discover Router|"discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.)'
+    'jira|Jira Router|"jira preview", "jira create", or "jira review <ID>"'
+    'integrations|Integrations Router|"integrations", "integrations jira-preview", or "integrations jira-create"'
+    'quick-review|Quick Review Command|"quick review" or "draft quick-review [file|pr <number>]"'
+    'deep-review|Deep Review Command|"deep review" or "draft deep-review [module]"'
+    'testing-strategy|Testing Strategy Command|"test strategy" or "draft testing-strategy [track <id>|path]"'
+    'learn|Learn Command|"learn patterns" or "draft learn [promote|migrate|path]"'
+    'adr|ADR Command|"document decision" or "draft adr [title]"'
+    'debug|Debug Command|"debug bug" or "draft debug [description|track <id>]"'
+    'standup|Standup Command|"standup" or "draft standup [date|week|save]"'
+    'tech-debt|Tech Debt Command|"tech debt" or "draft tech-debt [path|track <id>]"'
+    'incident-response|Incident Response Command|"incident" or "draft incident-response [new|update|postmortem]"'
+    'documentation|Documentation Command|"write docs" or "draft documentation [readme|runbook|api|onboarding]"'
+    'status|Status Command|"status" or "draft status"'
+    'revert|Revert Command|"revert" or "draft revert"'
+    'change|Change Command|"handle change" or "draft change <description>"'
+    'tour|Tour Command|"tour" or "draft tour"'
+    'impact|Impact Command|"impact" or "draft impact"'
+    'assist-review|Assist Review Command|"assist review" or "draft assist-review"'
+)
+
+# get_skill_header <skill> — display header for integration sections.
+get_skill_header() {
+    local skill="$1" row rest
+    for row in "${SKILL_META[@]}"; do
+        if [[ "${row%%|*}" == "$skill" ]]; then
+            rest="${row#*|}"
+            printf '%s\n' "${rest%%|*}"
+            return 0
+        fi
+    done
+    printf '%s\n' "$(echo "${skill:0:1}" | tr '[:lower:]' '[:upper:]')${skill:1} Command"
+}
+
+# get_copilot_trigger <skill> — natural-language trigger for the Copilot header.
+get_copilot_trigger() {
+    local skill="$1" row rest
+    for row in "${SKILL_META[@]}"; do
+        if [[ "${row%%|*}" == "$skill" ]]; then
+            rest="${row#*|}"
+            printf '%s\n' "${rest#*|}"
+            return 0
+        fi
+    done
+    printf '"draft %s"\n' "$skill"
+}
+
+
 # ─────────────────────────────────────────────────────────
 # Core reference files (inlined by Claude plugin at runtime)
 # ─────────────────────────────────────────────────────────
@@ -91,7 +166,6 @@ CORE_FILES=(
     "templates/ai-context.md"
     "templates/ai-profile.md"
     "templates/architecture.md"
-    "templates/track-architecture.md"
     "templates/jira.md"
     "templates/product.md"
     "templates/tech-stack.md"
@@ -181,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"
@@ -188,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"
@@ -202,6 +278,8 @@ TOOLS=(
     "okf-validate-quality.sh"
     "okf-coverage-check.sh"
     "okf-validate-all.sh"
+    "okf-emit-catalog.sh"
+    "okf-fix-links.sh"
 )
 
 # ─────────────────────────────────────────────────────────
@@ -264,12 +342,18 @@ extract_body() {
 }
 
 # Validate body format: line 1 blank, line 2 starts with #, line 3 blank.
+# $3 (optional): pre-extracted body — skips a second extract_body parse when
+# the caller already has it.
 validate_skill_body_format() {
     local skill="$1"
     local skill_file="$2"
 
     local body_head line1 line2 line3
-    body_head=$(extract_body "$skill_file" | sed -n '1,3p' || true)
+    if (( $# >= 3 )); then
+        body_head=$(printf '%s\n' "$3" | sed -n '1,3p')
+    else
+        body_head=$(extract_body "$skill_file" | sed -n '1,3p' || true)
+    fi
     line1=$(echo "$body_head" | sed -n '1p')
     line2=$(echo "$body_head" | sed -n '2p')
     line3=$(echo "$body_head" | sed -n '3p')

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;
@@ -28,9 +31,12 @@ if [[ "$(type -t memory_cli 2>/dev/null)" != function ]]; then
     source "$_GQ_DIR/_lib.sh"
 fi
 
-# Escape single quotes for embedding inside a Cypher single-quoted string literal.
+# Escape for embedding inside a Cypher single-quoted string literal.
+# Backslashes must be doubled BEFORE quotes are escaped, otherwise an input
+# ending in `\` yields `\'` — an escaped quote that never closes the literal.
 gq_escape() {
     local s="$1"
+    s="${s//\\/\\\\}"
     printf '%s' "${s//\'/\\\'}"
 }
 
@@ -40,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"; }
@@ -50,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"; }
@@ -82,19 +92,23 @@ gq_rows_len() {
     printf '%s' "$1" | jq -r '(.rows // []) | length' 2>/dev/null || printf '0'
 }
 
-# gq_symbol_status <project> <sym_esc> <result_json> -> ok | no-edges | no-match
+# gq_symbol_status <project> <sym_esc> <result_json>
+#   -> ok | no-edges | no-match | probe-failed
 # Fail-loud disambiguation (Guardrail 4): an empty result is only a true negative
 # ("no-edges") when the node actually exists; otherwise it is "no-match". An
 # existence probe runs only when the primary result is empty (hot path stays one
-# query).
+# query). If the probe itself errors, that is NOT a true negative — report
+# "probe-failed" so callers never mistake an engine failure for absence.
 gq_symbol_status() {
     local project="$1" sym="$2" result="$3"
     if [[ "$(gq_rows_len "$result")" -gt 0 ]]; then
         printf 'ok'; return
     fi
     local ex
-    ex="$(gq_run "$project" "$(gq_q_exists "$sym")" || true)"
-    if [[ -n "$ex" && "$(gq_rows_len "$ex")" -gt 0 ]]; then
+    if ! ex="$(gq_run "$project" "$(gq_q_exists "$sym")")"; then
+        printf 'probe-failed'; return
+    fi
+    if [[ "$(gq_rows_len "$ex")" -gt 0 ]]; then
         printf 'no-edges'
     else
         printf 'no-match'

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,9 +124,53 @@ get_yaml_field() {
     ' "$file"
 }
 
+# GitHub-flavored-markdown-ish heading id (shared by TOC, anchors, link fixers).
+# Keeps underscores; strips other punctuation; collapses whitespace to '-'.
+gfm_slug() {
+    local s="${1:-}"
+    # shellcheck disable=SC2001
+    s="$(printf '%s' "$s" | tr '[:upper:]' '[:lower:]')"
+    s="$(printf '%s' "$s" | sed -E 's/[^[:alnum:]_[:space:]-]+//g; s/[[:space:]]+/-/g; s/-+/-/g; s/^-+//; s/-+$//')"
+    printf '%s' "$s"
+}
+
+# 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"
+#     - "b"
+grounded_paths_count() {
+    local file="$1"
+    [[ -f "$file" ]] || { echo 0; return; }
+    awk '
+        NR==1 && /^---$/ { fm=1; next }
+        fm && /^---$/ { exit }
+        fm && /^x-grounded-paths:[[:space:]]*\[/ {
+            line=$0
+            sub(/^x-grounded-paths:[[:space:]]*\[/, "", line)
+            sub(/\].*$/, "", line)
+            gsub(/[[:space:]]/, "", line)
+            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; printed=1; exit }
+        }
+        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.
-# Preference: PATH > Draft-managed install (~/.cache/draft/bin) > vendored bin/<arch> under known roots.
+# 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"
@@ -157,14 +216,6 @@ find_memory_bin() {
     local roots=()
     [[ -n "$repo_abs" && -d "$repo_abs" ]] && roots+=("$repo_abs")
     [[ -n "$self_repo" && -d "$self_repo" ]] && roots+=("$self_repo")
-    for bc in \
-        "$HOME/.cursor/plugins/local/draft/.draft-install-path" \
-        "$HOME/.claude/plugins/draft/.draft-install-path"; do
-        if [[ -f "$bc" ]]; then
-            local pr; pr="$(cat "$bc" 2>/dev/null || true)"
-            [[ -n "$pr" && -d "$pr" ]] && roots+=("$pr")
-        fi
-    done
 
     for pr in "${roots[@]}"; do
         local cand="$pr/bin/$ARCH/$bin_name"
@@ -177,6 +228,21 @@ find_memory_bin() {
     return 1
 }
 
+# graph_bootstrap <repo-dir>
+# Shared engine bootstrap for the graph-*.sh wrappers: resolves the repo path,
+# locates the engine binary, checks jq, and ensures the index. Sets the globals
+# REPO_ABS and PROJECT. Returns 1 on any failure so each wrapper routes it to
+# its own unavailable-JSON shape (the shapes differ per tool).
+graph_bootstrap() {
+    local repo="$1" self_repo
+    REPO_ABS="$(cd "$repo" 2>/dev/null && pwd)" || return 1
+    self_repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+    find_memory_bin "$REPO_ABS" "$self_repo" || return 1
+    command -v jq >/dev/null 2>&1 || return 1
+    PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+    [[ -n "$PROJECT" ]] || return 1
+}
+
 # Run a codebase-memory-mcp CLI tool. Echoes the JSON result (stdout); the engine's
 # `level=...` log lines go to stderr and are discarded unless DRAFT_MEMORY_DEBUG is set.
 # Usage: memory_cli <tool> [json-args]
@@ -250,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/adr-index.sh

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

package/scripts/tools/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

@@ -51,8 +51,8 @@ while (($#)); do
         -h|--help) USAGE_HELP_MODE=1 usage ;;
         --enforce) ENFORCE=1; shift ;;
         --json) EMIT_JSON=1; shift ;;
-        --caps) CAPS_CONF="$2"; shift 2 ;;
-        --skills-dir) SKILLS_DIR="$2"; shift 2 ;;
+        --caps) CAPS_CONF="${2:?--caps requires a value}"; shift 2 ;;
+        --skills-dir) SKILLS_DIR="${2:?--skills-dir requires a value}"; shift 2 ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) printf 'Unexpected arg: %s\n' "$1" >&2; usage ;;
     esac
@@ -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 ;;