@drafthq/draft 2.7.0

package/scripts/tools/git-metadata.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env bash
+# git-metadata.sh — emit deterministic git metadata for Draft reports.
+#
+# Output is YAML frontmatter by default; --json emits the same fields as JSON.
+# Use --project-metadata to write/update draft/metadata.json (project-level
+# single source of truth for git state, used by all project-level artifacts).
+#
+# Usage:
+# scripts/tools/git-metadata.sh [--yaml|--json]
+# [--project NAME] [--module NAME]
+# [--track-id ID] [--generated-by CMD]
+# [--base BRANCH]
+# scripts/tools/git-metadata.sh --project-metadata [--project NAME]
+# [--generated-by CMD] [--base BRANCH]
+# [--output-dir DIR]
+#
+# Exit codes: 0 OK, 1 not a git repo or invocation error.
+set -euo pipefail
+
+# shellcheck source=_lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+
+FORMAT="yaml"
+PROJECT=""
+MODULE="root"
+TRACK_ID="null"
+GENERATED_BY=""
+BASE_BRANCH="main"
+WRITE_PROJECT_METADATA=0
+OUTPUT_DIR="."
+
+usage() {
+    cat <<'EOF'
+git-metadata.sh — emit deterministic git metadata for Draft reports.
+
+Usage:
+  scripts/tools/git-metadata.sh [--yaml|--json]
+                                [--project NAME] [--module NAME]
+                                [--track-id ID] [--generated-by CMD]
+                                [--base BRANCH]
+  scripts/tools/git-metadata.sh --project-metadata [--project NAME]
+                                [--generated-by CMD] [--base BRANCH]
+                                [--output-dir DIR]
+
+Flags:
+  --yaml Emit YAML frontmatter (default).
+  --json Emit JSON object.
+  --project-metadata Write git state to draft/metadata.json (project-level
+                          single source of truth). Creates the file if absent,
+                          merges git.* and synced_to_commit if present.
+  --project NAME Project name (default: basename of repo).
+  --module NAME Module name (default: "root").
+  --track-id ID Track id (default: null).
+  --generated-by CMD Command or skill name that produced the report.
+  --base BRANCH Upstream branch to compare against (default: main).
+  --output-dir DIR Directory containing draft/ (default: cwd). Used with
+                          --project-metadata.
+  --help Show this help.
+
+Exit codes: 0 OK, 1 not a git repo or invocation error.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --yaml) FORMAT="yaml"; shift;;
+        --json) FORMAT="json"; shift;;
+        --project-metadata) WRITE_PROJECT_METADATA=1; shift;;
+        --project) PROJECT="$2"; shift 2;;
+        --module) MODULE="$2"; shift 2;;
+        --track-id) TRACK_ID="$2"; shift 2;;
+        --generated-by) GENERATED_BY="$2"; shift 2;;
+        --base) BASE_BRANCH="$2"; shift 2;;
+        --output-dir) OUTPUT_DIR="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "ERROR: not inside a git repository" >&2
+    exit 1
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+if [[ -z "$PROJECT" ]]; then
+    PROJECT="$(basename "$REPO_ROOT")"
+fi
+
+LOCAL_BRANCH="$(git branch --show-current 2>/dev/null || echo "")"
+REMOTE_BRANCH="$(git rev-parse --abbrev-ref '@{upstream}' 2>/dev/null || echo "none")"
+FULL_SHA="$(git rev-parse HEAD)"
+SHORT_SHA="$(git rev-parse --short HEAD)"
+COMMIT_DATE="$(git log -1 --format=%cI HEAD)"
+COMMIT_MESSAGE="$(git log -1 --format=%s HEAD)"
+if [[ -n "$(git status --porcelain)" ]]; then
+    DIRTY="true"
+else
+    DIRTY="false"
+fi
+
+# Ahead/behind vs base (graceful fallback if base missing)
+AHEAD=0
+BEHIND=0
+if git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1; then
+    read -r BEHIND AHEAD < <(git rev-list --left-right --count "$BASE_BRANCH"...HEAD 2>/dev/null || echo "0 0")
+fi
+
+GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Escape double quotes in commit message for JSON/YAML safety
+escape_for_yaml() {
+    # YAML double-quoted strings use \" and \\ as escapes
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+# --project-metadata: write draft/metadata.json and exit
+if (( WRITE_PROJECT_METADATA )); then
+    DRAFT_DIR="$OUTPUT_DIR/draft"
+    META_FILE="$DRAFT_DIR/metadata.json"
+    if [[ ! -d "$DRAFT_DIR" ]]; then
+        echo "ERROR: $DRAFT_DIR not found — run draft:init first" >&2
+        exit 1
+    fi
+    CMD="${GENERATED_BY:-draft:init}"
+    _tmp="$(mktemp "${META_FILE}.XXXXXX")"
+    cat > "$_tmp" <<EOF
+{
+  "\$schema": "Draft Project Metadata Schema",
+  "\$description": "Single source of truth for project-level git state. Read by all project-level skills. Written by $CMD.",
+  "project": "$(json_escape "$PROJECT")",
+  "schema_version": "1.0.0",
+  "generated_by": "$(json_escape "$CMD")",
+  "generated_at": "$GENERATED_AT",
+  "git": {
+    "branch": "$(json_escape "$LOCAL_BRANCH")",
+    "remote": "$(json_escape "$REMOTE_BRANCH")",
+    "commit": "$FULL_SHA",
+    "commit_short": "$SHORT_SHA",
+    "commit_date": "$COMMIT_DATE",
+    "commit_message": "$(json_escape "$COMMIT_MESSAGE")",
+    "dirty": $DIRTY,
+    "base_branch": "$(json_escape "$BASE_BRANCH")",
+    "commits_ahead_base": $AHEAD,
+    "commits_behind_base": $BEHIND
+  },
+  "synced_to_commit": "$FULL_SHA"
+}
+EOF
+    mv -f "$_tmp" "$META_FILE"
+    echo "Written: $META_FILE (synced_to_commit=$FULL_SHA)"
+    exit 0
+fi
+
+if [[ "$FORMAT" == "json" ]]; then
+    cat <<EOF
+{
+  "project": "$(json_escape "$PROJECT")",
+  "module": "$(json_escape "$MODULE")",
+  "track_id": $([[ "$TRACK_ID" == "null" ]] && echo "null" || echo "\"$(json_escape "$TRACK_ID")\""),
+  "generated_by": $([[ -z "$GENERATED_BY" ]] && echo "null" || echo "\"$(json_escape "$GENERATED_BY")\""),
+  "generated_at": "$GENERATED_AT",
+  "git": {
+    "branch": "$(json_escape "$LOCAL_BRANCH")",
+    "remote": "$(json_escape "$REMOTE_BRANCH")",
+    "commit": "$FULL_SHA",
+    "commit_short": "$SHORT_SHA",
+    "commit_date": "$COMMIT_DATE",
+    "commit_message": "$(json_escape "$COMMIT_MESSAGE")",
+    "dirty": $DIRTY,
+    "base_branch": "$(json_escape "$BASE_BRANCH")",
+    "commits_ahead_base": $AHEAD,
+    "commits_behind_base": $BEHIND
+  },
+  "synced_to_commit": "$FULL_SHA"
+}
+EOF
+else
+    cat <<EOF
+---
+project: "$(escape_for_yaml "$PROJECT")"
+module: "$(escape_for_yaml "$MODULE")"
+track_id: $([[ "$TRACK_ID" == "null" ]] && echo "null" || echo "\"$(escape_for_yaml "$TRACK_ID")\"")
+generated_by: $([[ -z "$GENERATED_BY" ]] && echo "null" || echo "\"$(escape_for_yaml "$GENERATED_BY")\"")
+generated_at: "$GENERATED_AT"
+git:
+  branch: "$(escape_for_yaml "$LOCAL_BRANCH")"
+  remote: "$(escape_for_yaml "$REMOTE_BRANCH")"
+  commit: "$FULL_SHA"
+  commit_short: "$SHORT_SHA"
+  commit_date: "$COMMIT_DATE"
+  commit_message: "$(escape_for_yaml "$COMMIT_MESSAGE")"
+  dirty: $DIRTY
+  base_branch: "$(escape_for_yaml "$BASE_BRANCH")"
+  commits_ahead_base: $AHEAD
+  commits_behind_base: $BEHIND
+synced_to_commit: "$FULL_SHA"
+---
+EOF
+fi

package/scripts/tools/graph-callers.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# graph-callers.sh — enumerate direct callers of a function, from the knowledge graph.
+#
+# Replaces `graph --query --symbol <name> --mode callers`. Backed by the
+# codebase-memory-mcp engine via a single-hop CALLS openCypher pattern (the
+# dialect handles fixed-length patterns reliably).
+#
+# Usage:
+#   scripts/tools/graph-callers.sh --repo DIR --symbol NAME
+#
+# Output: JSON {symbol, callers:[{name,file}], source}.
+#   source = "memory-graph" | "unavailable"
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+
+REPO="."
+SYMBOL=""
+
+usage() {
+    cat <<'EOF'
+graph-callers.sh — direct callers of a function.
+
+Usage:
+  scripts/tools/graph-callers.sh --repo DIR --symbol NAME
+
+Flags:
+  --repo DIR     Repository root (default: cwd).
+  --symbol NAME  Function name to find callers of (required).
+  --help         Show this help.
+
+Output: JSON {symbol, callers, source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --symbol) SYMBOL="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$SYMBOL" ]] || { echo "ERROR: --symbol is required" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    jq -n --arg s "$SYMBOL" '{symbol:$s, callers:[], source:"unavailable"}' 2>/dev/null \
+        || echo '{"callers":[],"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
+
+# Escape single quotes in the symbol for the Cypher string literal.
+SYM_ESC="${SYMBOL//\'/\\\'}"
+Q="MATCH (c)-[:CALLS]->(f:Function {name:'$SYM_ESC'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200"
+RES="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q\"}" || echo '{}')"
+
+echo "${RES:-{\}}" | jq --arg s "$SYMBOL" '
+    {symbol:$s,
+     callers: [ (.rows // [])[] | {name:.[0], file:.[1]} ],
+     source:"memory-graph"}'

package/scripts/tools/graph-impact.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# graph-impact.sh — blast radius for a file or symbol, from the knowledge graph.
+#
+# Replaces `graph --query --file <path> --mode impact`. Backed by the
+# codebase-memory-mcp engine: combines detect_changes (git-diff → impacted
+# symbols, when querying the working tree) with trace_path callers for a named
+# function (transitive upstream dependents).
+#
+# Usage:
+#   scripts/tools/graph-impact.sh --repo DIR (--file PATH | --symbol NAME) [--depth N]
+#
+# Output: JSON {target, kind, impacted:[{name,file,hop}], source}.
+#   source = "memory-graph" | "unavailable"
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+
+REPO="."
+FILE=""
+SYMBOL=""
+DEPTH=3
+
+usage() {
+    cat <<'EOF'
+graph-impact.sh — blast radius for a file or symbol.
+
+Usage:
+  scripts/tools/graph-impact.sh --repo DIR (--file PATH | --symbol NAME) [--depth N]
+
+Flags:
+  --repo DIR     Repository root (default: cwd).
+  --file PATH    Size impact of a changed file (uses git working-tree diff).
+  --symbol NAME  Transitive callers of a function (default depth 3).
+  --depth N      Caller traversal depth for --symbol (default: 3).
+  --help         Show this help.
+
+Output: JSON {target, kind, impacted, source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --file) FILE="$2"; shift 2;;
+        --symbol) SYMBOL="$2"; shift 2;;
+        --depth) DEPTH="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$FILE" || -n "$SYMBOL" ]] || { echo "ERROR: provide --file or --symbol" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    local t="$1" k="$2"
+    jq -n --arg t "$t" --arg k "$k" '{target:$t, kind:$k, impacted:[], source:"unavailable"}' 2>/dev/null \
+        || echo '{"impacted":[],"source":"unavailable"}'
+    exit 2
+}
+
+if [[ -n "$SYMBOL" ]]; then TARGET="$SYMBOL"; KIND="symbol"; else TARGET="$FILE"; KIND="file"; fi
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable "$TARGET" "$KIND"
+command -v jq >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable "$TARGET" "$KIND"
+
+if [[ -n "$SYMBOL" ]]; then
+    # direction:"both" is the reliable form (the "callers" value returns empty in this engine);
+    # we read the .callers array from it.
+    RES="$(memory_cli trace_path "{\"project\":\"$PROJECT\",\"function_name\":\"$SYMBOL\",\"depth\":$DEPTH,\"direction\":\"both\"}" || echo '{}')"
+    echo "${RES:-{\}}" | jq --arg t "$TARGET" '
+        {target:$t, kind:"symbol",
+         impacted: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         source:"memory-graph"}'
+else
+    # File impact: detect_changes maps the working-tree diff to impacted symbols.
+    RES="$(memory_cli detect_changes "{\"project\":\"$PROJECT\"}" || echo '{}')"
+    echo "${RES:-{\}}" | jq --arg t "$TARGET" '
+        {target:$t, kind:"file",
+         impacted: [ (.impacted_symbols // [])[]
+                     | select((.file // "") | endswith($t) or (. == $t))
+                     | {name:.name, file:(.file // ""), hop:1} ],
+         source:"memory-graph"}'
+fi

package/scripts/tools/graph-snapshot.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# graph-snapshot.sh — materialize a lightweight, committed knowledge-graph snapshot.
+#
+# In the codebase-memory-mcp model, Claude Code skills query the engine live
+# (on-demand indexing into ~/.cache). This snapshot exists for the two cases
+# that cannot run the engine: PR-reviewable graph state, and the Copilot/Gemini
+# integrations (which read committed files, not MCP). It is small and derived —
+# git remains the source of truth.
+#
+# Writes under <repo>/draft/graph/:
+#   schema.yaml          engine + project metadata + counts (gates skill graph use)
+#   architecture.json    raw get_architecture(all) output
+#   hotspots.jsonl       fan-in-ranked symbols, one JSON object per line
+#   module-deps.mermaid  co-change coupling diagram
+#   proto-map.mermaid    detected-route diagram
+#
+# Usage: scripts/tools/graph-snapshot.sh [--repo DIR] [--out DIR]
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_lib.sh
+source "$TOOLS_DIR/_lib.sh"
+
+REPO="."
+OUT_DIR=""
+
+usage() {
+    cat <<'EOF'
+graph-snapshot.sh — write a committed knowledge-graph snapshot to draft/graph/.
+
+Usage:
+  scripts/tools/graph-snapshot.sh [--repo DIR] [--out DIR]
+
+Flags:
+  --repo DIR  Repository root (default: cwd).
+  --out DIR   Snapshot dir (default: <repo>/draft/graph).
+  --help      Show this help.
+
+Exit 0 on success, 2 when the graph engine is unavailable (no snapshot written).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --out) OUT_DIR="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
+OUT="${OUT_DIR:-$REPO_ABS/draft/graph}"
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || { echo "graph engine unavailable — no snapshot written" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "jq required for snapshot" >&2; exit 2; }
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || { echo "could not index repo — no snapshot written" >&2; exit 2; }
+
+mkdir -p "$OUT"
+
+# 1. architecture.json (full get_architecture)
+ARCH="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"all\"]}" || echo '{}')"
+echo "$ARCH" | jq '.' > "$OUT/architecture.json"
+
+# 2. hotspots.jsonl (one object per line)
+"$TOOLS_DIR/hotspot-rank.sh" --repo "$REPO_ABS" 2>/dev/null \
+    | jq -c '.hotspots[]?' > "$OUT/hotspots.jsonl" || true
+
+# 3. mermaid diagrams (best-effort; tools emit a stub + exit 2 if empty)
+"$TOOLS_DIR/mermaid-from-graph.sh" --repo "$REPO_ABS" --diagram module-deps > "$OUT/module-deps.mermaid" 2>/dev/null || true
+"$TOOLS_DIR/mermaid-from-graph.sh" --repo "$REPO_ABS" --diagram proto-map  > "$OUT/proto-map.mermaid"  2>/dev/null || true
+
+# 4. schema.yaml — metadata + gate for skill graph use
+NODES="$(echo "$ARCH" | jq -r '.total_nodes // 0')"
+EDGES="$(echo "$ARCH" | jq -r '.total_edges // 0')"
+HOTN="$(wc -l < "$OUT/hotspots.jsonl" | tr -d ' ')"
+VER="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}' || echo unknown)"
+cat > "$OUT/schema.yaml" <<EOF
+# Draft knowledge-graph snapshot — generated by scripts/tools/graph-snapshot.sh
+# Derived from the codebase-memory-mcp engine; git remains source of truth.
+engine: codebase-memory-mcp
+engine_version: "$VER"
+project: "$PROJECT"
+generated_at: "$(date -Iseconds 2>/dev/null || date)"
+nodes: $NODES
+edges: $EDGES
+hotspots: $HOTN
+artifacts:
+  - architecture.json
+  - hotspots.jsonl
+  - module-deps.mermaid
+  - proto-map.mermaid
+EOF
+
+echo "Snapshot written to $OUT (nodes=$NODES edges=$EDGES hotspots=$HOTN)"
+exit 0

package/scripts/tools/hotspot-rank.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# hotspot-rank.sh — emit complexity/fan-in-ranked symbols from the knowledge graph.
+#
+# Backed by the codebase-memory-mcp engine (get_architecture, server-computed
+# hotspot ranking by fan-in). Indexes the repo on demand if needed.
+#
+# Usage:
+#   scripts/tools/hotspot-rank.sh [--repo DIR] [--top N]
+#
+# Output: JSON {hotspots:[{id, name, fanIn}], source}.
+#   source = "memory-graph" | "unavailable"
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine/data unavailable.
+set -euo pipefail
+
+# shellcheck source=_lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+
+REPO="."
+TOP=0
+
+usage() {
+    cat <<'EOF'
+hotspot-rank.sh — fan-in-ranked symbols from the knowledge graph.
+
+Usage:
+  scripts/tools/hotspot-rank.sh [--repo DIR] [--top N]
+
+Flags:
+  --repo DIR  Repository root (default: cwd).
+  --top N     Keep only top N hotspots (default: 0 = all).
+  --help      Show this help.
+
+Output: JSON {hotspots:[{id, name, fanIn}], source}.
+  source = "memory-graph" | "unavailable"
+
+Exit 0 with results, exit 2 with {"hotspots":[],"source":"unavailable"} when the
+graph engine is unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --top) TOP="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+if [[ ! -d "$REPO" ]]; then
+    echo "ERROR: --repo '$REPO' is not a directory" >&2
+    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
+
+ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"hotspots\"]}" || true)"
+[[ -n "$ARCH_JSON" ]] || unavailable
+
+echo "$ARCH_JSON" | jq --argjson top "$TOP" '
+    {
+      hotspots: ([ (.hotspots // [])[] | {id: .qualified_name, name: .name, fanIn: .fan_in} ]
+                 | if $top > 0 then .[0:$top] else . end),
+      source: "memory-graph"
+    }'

package/scripts/tools/manage-symlinks.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# manage-symlinks.sh — refresh the "<kind>-latest.md" symlink in a directory.
+#
+# Finds the newest file matching "<kind>-report-*.md" in DIR and points
+# "<kind>-report-latest.md" at it. Selection is by filename sort order
+# (timestamps embedded in filenames), not mtime, so result is reproducible.
+#
+# Usage:
+# scripts/tools/manage-symlinks.sh <DIR> <KIND>
+#
+# Exit codes: 0 created/refreshed, 1 invocation error, 2 no matching files.
+set -euo pipefail
+
+DIR=""
+KIND=""
+
+usage() {
+    cat <<'EOF'
+manage-symlinks.sh — point "<kind>-report-latest.md" at the newest timestamped report.
+
+Usage:
+  scripts/tools/manage-symlinks.sh <DIR> <KIND>
+
+Positional:
+  DIR Directory containing <kind>-report-<timestamp>.md files.
+  KIND Report kind (e.g. "bughunt", "review", "standup").
+
+Flags:
+  --help Show this help.
+
+Selects the highest-sorted filename, creates/refreshes <kind>-report-latest.md
+(relative symlink). Emits the chosen target filename to stdout.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *)
+            if [[ -z "$DIR" ]]; then DIR="$1"
+            elif [[ -z "$KIND" ]]; then KIND="$1"
+            else echo "Unexpected arg: $1" >&2; exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$DIR" || -z "$KIND" ]]; then
+    usage >&2
+    exit 1
+fi
+
+if [[ ! -d "$DIR" ]]; then
+    echo "ERROR: '$DIR' is not a directory" >&2
+    exit 1
+fi
+
+# Validate KIND (kebab-case-ish; no slashes, dots, or spaces)
+if [[ ! "$KIND" =~ ^[a-z][a-z0-9-]*$ ]]; then
+    echo "ERROR: KIND must be kebab-case (got: '$KIND')" >&2
+    exit 1
+fi
+
+pattern="$KIND-report-*.md"
+latest_name="$KIND-report-latest.md"
+
+# Exclude the latest symlink itself from selection.
+newest=""
+while IFS= read -r -d '' f; do
+    base="$(basename "$f")"
+    [[ "$base" == "$latest_name" ]] && continue
+    # File-only (not symlink we already manage)
+    if [[ -L "$f" ]]; then continue; fi
+    newest="$base"
+done < <(find "$DIR" -maxdepth 1 -name "$pattern" -print0 | sort -z)
+
+if [[ -z "$newest" ]]; then
+    echo "No matching $pattern files in $DIR" >&2
+    exit 2
+fi
+
+(cd "$DIR" && ln -sfn "$newest" "$latest_name")
+echo "$newest"