@drafthq/draft 2.7.0

package/scripts/tools/verify-citations.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# verify-citations.sh
+#
+# Resolve every `path:line` and `path:line-range` citation in a track's
+# Markdown against the commit pinned in `metadata.json:synced_to_commit`,
+# and confirm the cited content still resides within the line window.
+#
+# Drift tolerance is configurable (default ±5 lines). Citations wrapped
+# inside <!-- VERIFIER:IGNORE START --> ... <!-- VERIFIER:IGNORE END -->
+# blocks are skipped. Citations annotated as `(planned)` or carrying a
+# `[New file ...]` annotation are skipped (must not exist yet).
+#
+# Usage:
+# scripts/tools/verify-citations.sh # scan ./tracks/*
+# scripts/tools/verify-citations.sh tracks/foo # scan one
+# scripts/tools/verify-citations.sh --tolerance 10 --json tracks/foo
+#
+# Exit codes:
+# 0 clean
+# 1 drift detected
+# 2 usage / runtime error
+
+set -euo pipefail
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+    echo "${0##*/} — Foundations quality tool (see core/ docs for full behavior)"
+    exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/_lib.sh"
+
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+EMIT_JSON=0
+TOLERANCE=5
+TRACK_PATHS=()
+
+usage() {
+    local stream=2 code=2
+    if [[ "${USAGE_HELP_MODE:-0}" == 1 ]]; then stream=1; code=0; fi
+    sed -n '2,20p' "$0" >&$stream
+    exit "$code"
+}
+
+while (($#)); do
+    case "$1" in
+        -h|--help) USAGE_HELP_MODE=1 usage ;;
+        --json) EMIT_JSON=1; shift ;;
+        --tolerance) TOLERANCE="$2"; shift 2 ;;
+        -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
+        *) TRACK_PATHS+=("$1"); shift ;;
+    esac
+done
+
+if ((${#TRACK_PATHS[@]} == 0)); then
+    while IFS= read -r p; do TRACK_PATHS+=("$p"); done < <(discover_track_dirs "$REPO_ROOT")
+fi
+
+violation_count=0
+declare -a violations=()
+
+record() {
+    violations+=("$1|$2|$3|$4|$5")
+    violation_count=$((violation_count + 1))
+}
+
+# Extract citations from a markdown file, skipping VERIFIER:IGNORE blocks.
+# Output: file<TAB>line<TAB>cite (cite is path:LINE or path:LINE-LINE).
+extract_citations() {
+    local md="$1"
+    awk '
+        BEGIN { ignore = 0 }
+        /<!-- VERIFIER:IGNORE START -->/ { ignore = 1; next }
+        /<!-- VERIFIER:IGNORE END -->/ { ignore = 0; next }
+        ignore == 1 { next }
+        /\(planned\)|\[New file/ { next }
+        {
+            s = $0
+            gsub(/https?:\/\/[^[:space:]]*/, "", s)
+            # Use a string regex (not a /.../ literal): a literal "/" inside a
+            # bracket expression prematurely terminates a regex literal in
+            # POSIX/BSD awk ("nonterminated character class"), though gawk is
+            # lenient. The string form is portable across awk implementations.
+            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+")) {
+                cite = substr(s, RSTART, RLENGTH)
+                printf("%s\t%d\t%s\n", FILENAME, NR, cite)
+                s = substr(s, RSTART + RLENGTH)
+            }
+        }
+    ' "$md"
+}
+
+# Resolve cite against the synced_to_commit content using git show.
+# Returns 0 if match within tolerance, 1 if past-EOF, 2 if file truly missing.
+#
+# When the cite is a bare basename (no slash) and the literal path doesn't
+# exist at the commit, fall back to a basename search across the tree — this
+# accepts narrative citations like `foo.cc:42` that mean `path/to/foo.cc:42`.
+# Skipped when multiple files share the basename (ambiguous → reject).
+verify_one_citation() {
+    local repo_root="$1" commit="$2" cite="$3"
+    local path lo hi
+    path="${cite%%:*}"
+    local range="${cite#*:}"
+    if [[ "$range" == *-* ]]; then
+        lo="${range%%-*}"
+        hi="${range##*-}"
+    else
+        lo="$range"
+        hi="$range"
+    fi
+    path="${path#./}"
+
+    local resolved_path="$path"
+
+    # Probe via git show.
+    if ! git -C "$repo_root" cat-file -e "$commit":"$path" 2>/dev/null; then
+        # Bare-basename fallback: if the cite carries no slash, search the
+        # tree for files whose basename matches and accept when unique.
+        if [[ "$path" != */* ]]; then
+            local matches
+            matches="$(git -C "$repo_root" ls-tree -r --name-only "$commit" 2>/dev/null \
+                | awk -v b="$path" 'BEGIN{FS="/"} $NF==b{print}')"
+            local match_count
+            match_count="$(printf '%s\n' "$matches" | grep -c . || true)"
+            if (( match_count == 1 )); then
+                resolved_path="$matches"
+            elif (( match_count > 1 )); then
+                printf 'ambiguous-basename|%s has %d candidates: %s\n' \
+                    "$path" "$match_count" \
+                    "$(printf '%s' "$matches" | tr '\n' ',' | sed 's/,$//')"
+                return 1
+            else
+                return 2
+            fi
+        else
+            return 2
+        fi
+    fi
+
+    local total_lines
+    total_lines="$(git -C "$repo_root" show "$commit":"$resolved_path" 2>/dev/null | wc -l | tr -d ' ')"
+    if (( lo < 1 )); then
+        printf 'invalid-line|cite %s has line < 1\n' "$cite"
+        return 1
+    fi
+    if (( hi > total_lines + TOLERANCE )); then
+        printf 'past-eof|file %s has %d lines, cite %s exceeds (+tol %d)\n' \
+            "$resolved_path" "$total_lines" "$cite" "$TOLERANCE"
+        return 1
+    fi
+    if (( lo > total_lines + TOLERANCE )); then
+        printf 'past-eof|file %s has %d lines, cite %s start exceeds (+tol %d)\n' \
+            "$resolved_path" "$total_lines" "$cite" "$TOLERANCE"
+        return 1
+    fi
+    return 0
+}
+
+scan_one_track() {
+    local track_dir="$1"
+    local rel_track="${track_dir#"$REPO_ROOT/"}"
+    local meta="$track_dir/metadata.json"
+    local commit=""
+    if [[ -f "$meta" ]]; then
+        commit="$(read_json_str "$meta" "synced_to_commit")"
+    fi
+    if [[ -z "$commit" ]]; then
+        # Fall back to YAML frontmatter on spec.md if present.
+        [[ -f "$track_dir/spec.md" ]] && commit="$(get_yaml_field "$track_dir/spec.md" "synced_to_commit")"
+    fi
+    if [[ -z "$commit" ]]; then
+        record "$rel_track" "no-pinned-commit" "metadata.json" "0" \
+            "no synced_to_commit; cannot verify citations"
+        return
+    fi
+
+    # Determine which git repo to query. Prefer the track's enclosing repo
+    # (first git dir above the track_dir). Fall back to Draft repo.
+    local probe="$track_dir"
+    local target_repo=""
+    while [[ "$probe" != "/" ]]; do
+        if [[ -e "$probe/.git" ]]; then target_repo="$probe"; break; fi
+        probe="$(dirname "$probe")"
+    done
+    [[ -z "$target_repo" ]] && target_repo="$REPO_ROOT"
+
+    while IFS= read -r f; do
+        local rel_md="${f#"$track_dir/"}"
+        while IFS=$'\t' read -r md_file lineno cite; do
+            local md_line="$md_file"
+            local result rc=0
+            # set +e to capture rc; set -e would exit on a non-zero return.
+            set +e
+            result="$(verify_one_citation "$target_repo" "$commit" "$cite" 2>&1)"
+            rc=$?
+            set -e
+            if (( rc == 1 )); then
+                record "$rel_track" "cite-drift" "$rel_md" "$lineno" \
+                    "$cite — $result"
+            elif (( rc == 2 )); then
+                record "$rel_track" "cite-missing-file" "$rel_md" "$lineno" \
+                    "$cite — file not present at commit $commit"
+            fi
+        done < <(extract_citations "$f")
+    done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
+}
+
+for t in "${TRACK_PATHS[@]}"; do
+    [[ -d "$t" ]] || { record "$t" "not-a-directory" "" "0" ""; continue; }
+    scan_one_track "$(cd "$t" && pwd)"
+done
+
+emit() {
+    if ((EMIT_JSON)); then
+        printf '{"violation_count": %d, "tolerance": %d, "violations": [\n' \
+            "$violation_count" "$TOLERANCE"
+        local first=1 v track kind file line detail
+        # Guard the expansion: "${arr[@]}" on an empty array is an unbound-variable
+        # error under `set -u` in bash <= 4.3 (e.g. macOS).
+        if ((violation_count > 0)); then
+            for v in "${violations[@]}"; do
+                IFS='|' read -r track kind file line detail <<< "$v"
+                if ((first)); then first=0; else printf ',\n'; fi
+                printf ' {"track":"%s","kind":"%s","file":"%s","line":%s,"detail":"%s"}' \
+                    "$(json_escape "$track")" "$(json_escape "$kind")" \
+                    "$(json_escape "$file")" "${line:-0}" "$(json_escape "$detail")"
+            done
+        fi
+        printf '\n]}\n'
+    else
+        if ((violation_count == 0)); then
+            printf 'OK: citations clean across %d track(s) (tol=±%d).\n' \
+                "${#TRACK_PATHS[@]}" "$TOLERANCE"
+        else
+            printf 'CITATIONS: %d violation(s) across %d track(s) (tol=±%d).\n' \
+                "$violation_count" "${#TRACK_PATHS[@]}" "$TOLERANCE" >&2
+            local v track kind file line detail
+            for v in "${violations[@]}"; do
+                IFS='|' read -r track kind file line detail <<< "$v"
+                printf ' [%s] %s/%s:%s — %s\n' "$kind" "$track" "$file" "$line" "$detail" >&2
+            done
+        fi
+    fi
+}
+emit
+
+((violation_count == 0))

package/scripts/tools/verify-doc-anchors.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# verify-doc-anchors.sh
+
+#
+# Verify cross-document references in a track:
+# - §X.Y or §X numbered-section references → target document must contain
+# a heading whose text starts with that number.
+# - <doc>.md#<anchor> markdown anchors → resolve <anchor> against the
+# target file's header slugs.
+# - (planned) / [New file ...] annotations → file MUST NOT exist locally.
+#
+# Skips content inside <!-- VERIFIER:IGNORE START --> ... END --> blocks.
+#
+# Usage:
+# scripts/tools/verify-doc-anchors.sh # scan ./tracks/*
+# scripts/tools/verify-doc-anchors.sh tracks/foo # scan one
+# scripts/tools/verify-doc-anchors.sh --json ...
+#
+# Exit codes:
+# 0 clean
+# 1 anchor violation
+# 2 usage / runtime error
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/_lib.sh"
+
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+EMIT_JSON=0
+TRACK_PATHS=()
+
+usage() {
+    local stream=2 code=2
+    if [[ "${USAGE_HELP_MODE:-0}" == 1 ]]; then stream=1; code=0; fi
+    sed -n '2,20p' "$0" >&$stream
+    exit "$code"
+}
+
+while (($#)); do
+    case "$1" in
+        -h|--help) USAGE_HELP_MODE=1 usage ;;
+        --json) EMIT_JSON=1; shift ;;
+        -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
+        *) TRACK_PATHS+=("$1"); shift ;;
+    esac
+done
+
+if ((${#TRACK_PATHS[@]} == 0)); then
+    while IFS= read -r p; do TRACK_PATHS+=("$p"); done < <(
+        find "$REPO_ROOT" -type d -path '*/tracks/*' -maxdepth 4 -mindepth 2 \
+            -not -path '*/.*' 2>/dev/null | sort
+    )
+fi
+
+violation_count=0
+declare -a violations=()
+record() { violations+=("$1|$2|$3|$4|$5"); violation_count=$((violation_count + 1)); }
+
+# Build a deduplicated list of header slugs from a markdown file.
+# Standard GitHub-flavored slug: lowercase, spaces → '-', strip punctuation.
+md_slugs() {
+    awk '
+        /^#{1,6} +/ {
+            s = $0
+            sub(/^#+ +/, "", s)
+            # Strip trailing whitespace
+            sub(/[[:space:]]+$/, "", s)
+            # Lowercase
+            s = tolower(s)
+            # Replace spaces with dashes
+            gsub(/ +/, "-", s)
+            # Strip punctuation except dashes
+            gsub(/[^a-z0-9-]/, "", s)
+            print s
+        }
+    ' "$1" | sort -u
+}
+
+# Extract numbered headers (e.g. "## 7 Parallel SST transfer" or "## 20.2 ...").
+md_numbered_headers() {
+    awk '
+        /^#{1,6} +[0-9]+(\.[0-9]+)*[ .]/ {
+            s = $0
+            sub(/^#+ +/, "", s)
+            print s
+        }
+    ' "$1"
+}
+
+scan_md() {
+    local track_dir="$1" md="$2"
+    local rel_track="${track_dir#"$REPO_ROOT/"}"
+    local rel_md="${md#"$track_dir/"}"
+    local ignore=0 lineno=0
+    while IFS= read -r line; do
+        lineno=$((lineno + 1))
+        if [[ "$line" == *"<!-- VERIFIER:IGNORE START -->"* ]]; then ignore=1; continue; fi
+        if [[ "$line" == *"<!-- VERIFIER:IGNORE END -->"* ]]; then ignore=0; continue; fi
+        (( ignore )) && continue
+
+        # 1. §-references inside a markdown link.
+        # Plain-prose `§X.Y` is too ambiguous in practice — authors commonly
+        # use it as shorthand for an external doc (e.g. `architecture.md §20.2`)
+        # without naming the file on the same line. To keep this validator
+        # focused on machine-verifiable cross-references, we only check
+        # §X.Y when it appears INSIDE a markdown link target — i.e. the
+        # author has structurally committed to an in-track reference.
+        # Example that IS validated:
+        # [see §3.1](./hld.md#detailed-design) ← anchor check below
+        # Example that is NOT validated (prose only):
+        # The §20.2 layout matches architecture.md.
+        # If a track wants stricter intra-track §-checks, it can use
+        # markdown links pointing to numbered headers explicitly.
+        : # §-ref prose validation disabled — see comment above.
+
+        # 2. Markdown anchor references like ./hld.md#section-name
+        if echo "$line" | grep -qE '\([^)]*\.md#[A-Za-z0-9_-]+\)'; then
+            local m
+            while IFS= read -r m; do
+                m="${m#(}"; m="${m%)}"
+                local path="${m%%#*}"
+                local anchor="${m##*#}"
+                local target
+                if [[ "$path" == /* ]]; then
+                    target="$path"
+                else
+                    target="$track_dir/${path#./}"
+                fi
+                if [[ ! -f "$target" ]]; then
+                    record "$rel_track" "missing-doc" "$rel_md" "$lineno" \
+                        "anchor target file not found: $path"
+                    continue
+                fi
+                if ! md_slugs "$target" | grep -Fxq "$anchor"; then
+                    record "$rel_track" "missing-anchor" "$rel_md" "$lineno" \
+                        "$path has no slug '$anchor'"
+                fi
+            done < <(echo "$line" | grep -oE '\([^)]*\.md#[A-Za-z0-9_-]+\)')
+        fi
+
+        # 3. (planned) / [New file ...] annotations: the path mentioned on the
+        # same line must NOT yet exist relative to the track.
+        #
+        # Only fire when the line has EXACTLY one path-looking token. Lines
+        # with multiple paths (e.g. "Flag X (planned) — wired per `spec.md`")
+        # make attribution ambiguous; the validator should not guess which
+        # token the `(planned)` annotation owns.
+        if echo "$line" | grep -qE '\(planned\)|\[New file'; then
+            local paths
+            paths="$(echo "$line" | grep -oE '[A-Za-z][A-Za-z0-9_./-]*\.[A-Za-z]+' | sort -u)"
+            local path_count
+            path_count="$(printf '%s\n' "$paths" | grep -c . || true)"
+            if (( path_count == 1 )); then
+                local p="$paths"
+                local rel="${p#./}"
+                if [[ -e "$track_dir/$rel" ]]; then
+                    record "$rel_track" "planned-file-exists" "$rel_md" "$lineno" \
+                        "$p annotated planned but exists at $track_dir/$rel"
+                fi
+            fi
+        fi
+    done < "$md"
+}
+
+for t in "${TRACK_PATHS[@]}"; do
+    [[ -d "$t" ]] || { record "$t" "not-a-directory" "" "0" ""; continue; }
+    track_dir="$(cd "$t" && pwd)"
+    while IFS= read -r f; do
+        scan_md "$track_dir" "$f"
+    done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
+done
+
+emit() {
+    if ((EMIT_JSON)); then
+        printf '{"violation_count": %d, "violations": [\n' "$violation_count"
+        local first=1 v track kind file line detail
+        for v in "${violations[@]}"; do
+            IFS='|' read -r track kind file line detail <<< "$v"
+            if ((first)); then first=0; else printf ',\n'; fi
+            printf ' {"track":"%s","kind":"%s","file":"%s","line":%s,"detail":"%s"}' \
+                "$(json_escape "$track")" "$(json_escape "$kind")" \
+                "$(json_escape "$file")" "${line:-0}" "$(json_escape "$detail")"
+        done
+        printf '\n]}\n'
+    else
+        if ((violation_count == 0)); then
+            printf 'OK: anchors clean across %d track(s).\n' "${#TRACK_PATHS[@]}"
+        else
+            printf 'ANCHORS: %d violation(s) across %d track(s).\n' \
+                "$violation_count" "${#TRACK_PATHS[@]}" >&2
+            local v track kind file line detail
+            for v in "${violations[@]}"; do
+                IFS='|' read -r track kind file line detail <<< "$v"
+                printf ' [%s] %s/%s:%s — %s\n' "$kind" "$track" "$file" "$line" "$detail" >&2
+            done
+        fi
+    fi
+}
+emit
+
+((violation_count == 0))

package/scripts/tools/verify-graph-binary.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# verify-graph-binary.sh — validate and select the Draft knowledge-graph engine.
+#
+# The engine is the codebase-memory-mcp binary. Resolution order (see _lib.sh:find_memory_bin):
+#   1. DRAFT_MEMORY_BIN override
+#   2. codebase-memory-mcp on $PATH
+#   3. Draft-managed install (~/.cache/draft/bin/)
+#   4. Vendored arch-specific under bin/<arch>/
+#
+# Emits JSON or a human report. Exit 0 = found+usable, 2 = none (graceful for skills).
+#
+# Usage:
+#   scripts/tools/verify-graph-binary.sh [--repo <dir>] [--plugin-root <dir>] [--json] [--verbose] [--strict]
+#
+# --strict : fail (exit 2) when no engine is found (release/CI gates)
+# Integrates with install/package and the skills/init graph step.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+REPO="."
+PLUGIN_ROOT=""
+EMIT_JSON=0
+VERBOSE=0
+STRICT=0
+
+usage() {
+  cat <<'EOF'
+verify-graph-binary.sh — Draft knowledge-graph engine resolver + verifier
+
+Engine: codebase-memory-mcp
+Resolution: DRAFT_MEMORY_BIN > PATH > ~/.cache/draft/bin > bin/<arch>/
+
+Options:
+  --repo DIR         Repo root for context (default .)
+  --plugin-root DIR  Explicit Draft plugin install root
+  --json             Emit JSON report
+  --verbose          Human progress
+  --strict           Exit 2 if no engine found
+  --help             This message
+
+Exit codes:
+  0  Usable engine found and responsive to --version
+  1  Bad args
+  2  No engine located
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo) REPO="$2"; shift 2 ;;
+    --plugin-root) PLUGIN_ROOT="$2"; shift 2 ;;
+    --json) EMIT_JSON=1; shift ;;
+    --verbose) VERBOSE=1; shift ;;
+    --strict) STRICT=1; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+log() { [[ $VERBOSE -eq 1 ]] && echo "[verify-graph] $*" >&2 || true; }
+
+# Resolve architecture string for the report (linux-amd64, darwin-arm64, ...).
+resolve_arch() {
+  local os arch
+  os=$(uname -s | tr '[:upper:]' '[:lower:]')
+  arch=$(uname -m)
+  case "$arch" in
+    x86_64|amd64) arch="amd64" ;;
+    aarch64|arm64) arch="arm64" ;;
+    armv7l) arch="arm" ;;
+  esac
+  echo "${os}-${arch}"
+}
+
+ARCH="$(resolve_arch)"
+log "Resolved arch: $ARCH"
+
+REPO_ABS="$(cd "$REPO" 2>/dev/null && pwd || echo "$REPO")"
+SELF_REPO="${PLUGIN_ROOT:-$SCRIPT_DIR/../..}"
+
+# Classify the resolution source for reporting.
+classify_source() {
+  case "$MEMORY_BIN" in
+    "$HOME/.cache/draft/bin/"*) echo "managed" ;;
+    */bin/"$ARCH"/*) echo "bundled:$ARCH" ;;
+    codebase-memory-mcp) echo "path" ;;
+    "${DRAFT_MEMORY_BIN:-__none__}") echo "override" ;;
+    *) echo "path" ;;
+  esac
+}
+
+MEMORY_BIN=""
+if ! find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
+  if [[ $EMIT_JSON -eq 1 ]]; then
+    local_msg="No codebase-memory-mcp engine found in DRAFT_MEMORY_BIN, PATH, ~/.cache/draft/bin, or bin/<arch>/"
+    if [[ $STRICT -eq 1 ]]; then
+      printf '{"status":"none","engine_bin":null,"source":null,"arch":"%s","message":"strict mode: %s"}\n' "$ARCH" "$local_msg"
+    else
+      printf '{"status":"unavailable","engine_bin":null,"source":null,"arch":"%s","message":"%s"}\n' "$ARCH" "$local_msg"
+    fi
+  elif [[ $STRICT -eq 1 ]]; then
+    echo "STRICT: No codebase-memory-mcp engine found." >&2
+  else
+    echo "ERROR: No Draft graph engine located (codebase-memory-mcp)." >&2
+    echo "        Install it (scripts/fetch-memory-engine.sh) or put it on PATH." >&2
+  fi
+  exit 2
+fi
+
+SOURCE="$(classify_source)"
+log "Selected engine: $MEMORY_BIN (source=$SOURCE)"
+
+# Liveness: must respond to --version.
+if ! "$MEMORY_BIN" --version >/dev/null 2>&1; then
+  log "Selected engine failed --version"
+  echo "ERROR: engine $MEMORY_BIN found but failed --version (wrong OS/arch or corrupt?)." >&2
+  if [[ $EMIT_JSON -eq 1 ]]; then
+    printf '{"status":"unusable","engine_bin":"%s","source":"%s","arch":"%s"}\n' \
+      "$(json_escape "$MEMORY_BIN")" "$(json_escape "$SOURCE")" "$ARCH"
+  fi
+  exit 2
+fi
+
+STATUS="ok"
+
+if [[ $EMIT_JSON -eq 1 ]]; then
+  printf '{"status":"%s","engine_bin":"%s","source":"%s","arch":"%s"}\n' \
+    "$(json_escape "$STATUS")" "$(json_escape "$MEMORY_BIN")" "$(json_escape "$SOURCE")" "$(json_escape "$ARCH")"
+else
+  echo "Draft graph engine: $MEMORY_BIN"
+  echo "  source: $SOURCE (arch=$ARCH)"
+  echo "  status: $STATUS"
+fi
+
+# Usage report side-effect when in a draft/ context (graph-usage-report contract).
+if [[ -d "$REPO/draft" ]]; then
+  mkdir -p "$REPO/draft"
+  cat > "$REPO/draft/.graph-binary-report.json" <<EOF
+{
+  "detected_at": "$(date -Iseconds 2>/dev/null || date)",
+  "engine_bin": "$(json_escape "$MEMORY_BIN")",
+  "source": "$(json_escape "$SOURCE")",
+  "arch": "$(json_escape "$ARCH")",
+  "status": "$(json_escape "$STATUS")"
+}
+EOF
+  log "Wrote draft/.graph-binary-report.json (usage report contract)"
+fi
+
+exit 0