@drafthq/draft 2.7.0

package/scripts/tools/adr-index.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# adr-index.sh — index Architecture Decision Records.
+#
+# Walks --root and emits a JSON {adrs:[{id,title,date,status,path,related_tracks}]}.
+# Default --root is <cwd>/draft/adrs. id is derived from filename prefix (NNN-…) when
+# present, else filename without extension.
+#
+# Usage:
+# scripts/tools/adr-index.sh [--root DIR]
+set -euo pipefail
+
+# shellcheck source=_lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+
+ROOT=""
+
+usage() {
+    cat <<'EOF'
+adr-index.sh — emit a JSON index of ADR files.
+
+Usage:
+  scripts/tools/adr-index.sh [--root DIR]
+
+Flags:
+  --root DIR Directory containing ADR markdown files (default: draft/adrs).
+  --help Show this help.
+
+Reads YAML frontmatter (title, date, status, related_tracks) from each ADR file.
+Output: {adrs:[{id,title,date,status,path,related_tracks}]}
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --root) ROOT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+if [[ -z "$ROOT" ]]; then
+    ROOT="draft/adrs"
+fi
+
+if [[ ! -d "$ROOT" ]]; then
+    printf '{"adrs":[]}\n'
+    exit 0
+fi
+
+# Related tracks: YAML list under "related_tracks:" — one item per line like " - XYZ".
+get_related_tracks() {
+    local file="$1"
+    awk '
+        NR == 1 && /^---$/ { in_fm = 1; next }
+        in_fm && /^---$/ { exit }
+        in_fm {
+            if ($0 ~ /^related_tracks:/) { in_list = 1; next }
+            if (in_list) {
+                if ($0 ~ /^[[:space:]]*-[[:space:]]+/) {
+                    v = $0
+                    sub(/^[[:space:]]*-[[:space:]]+/, "", v)
+                    gsub(/^"/, "", v); gsub(/"$/, "", v)
+                    print v
+                } else if ($0 !~ /^[[:space:]]/) {
+                    in_list = 0
+                }
+            }
+        }
+    ' "$file"
+}
+
+first=true
+printf '{"adrs":['
+while IFS= read -r -d '' file; do
+    base="$(basename "$file")"
+    id="${base%.md}"
+    if [[ "$base" =~ ^([0-9]+)- ]]; then
+        id="${BASH_REMATCH[1]}"
+    fi
+
+    title="$(get_yaml_field "$file" title)"
+    date_val="$(get_yaml_field "$file" date)"
+    status="$(get_yaml_field "$file" status)"
+
+    # If no title in frontmatter, fallback to first H1.
+    if [[ -z "$title" ]]; then
+        title="$(grep -m1 '^# ' "$file" 2>/dev/null | sed 's/^#\s*//' || true)"
+    fi
+
+    tracks=()
+    while IFS= read -r tr; do
+        [[ -n "$tr" ]] && tracks+=("$tr")
+    done < <(get_related_tracks "$file")
+
+    tr_json='['
+    tr_first=true
+    for t in "${tracks[@]+"${tracks[@]}"}"; do
+        if $tr_first; then tr_first=false; else tr_json+=','; fi
+        tr_json+="\"$(json_escape "$t")\""
+    done
+    tr_json+=']'
+
+    if $first; then first=false; else printf ','; fi
+    printf '\n {"id":"%s","title":"%s","date":"%s","status":"%s","path":"%s","related_tracks":%s}' \
+        "$(json_escape "$id")" \
+        "$(json_escape "$title")" \
+        "$(json_escape "$date_val")" \
+        "$(json_escape "$status")" \
+        "$(json_escape "$file")" \
+        "$tr_json"
+done < <(find "$ROOT" -maxdepth 2 -type f -name '*.md' -print0 2>/dev/null | sort -z)
+
+if $first; then
+    printf ']}\n'
+else
+    printf '\n]}\n'
+fi

package/scripts/tools/check-graph-usage-report.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# check-graph-usage-report.sh — validate that a skill output / template contains
+# the mandatory Graph Usage Report footer required by core/shared/graph-query.md.
+#
+# Usage:
+# check-graph-usage-report.sh <file> [<file> ...]
+#
+# Behavior:
+# - Exits 0 when every input file contains a well-formed `## Graph Usage Report`
+# section with the five required bullets.
+# - Exits 1 when any file is missing the section or any required bullet.
+# - Exits 2 on usage error (no files supplied, missing argument).
+#
+# A file is exempt if the very first line matches `<!-- graph-usage-report:skip -->`
+# (intended for non-code-touching templates that legitimately have no graph step).
+
+set -euo pipefail
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+    cat <<'EOF'
+check-graph-usage-report.sh — validate that a skill output / template contains
+the mandatory Graph Usage Report footer required by core/shared/graph-query.md.
+
+Usage:
+  check-graph-usage-report.sh <file> [<file> ...]
+
+Required bullets under the `## Graph Usage Report` section:
+  - Graph files queried:
+  - Modules identified via graph:
+  - Files identified via graph:
+  - Filesystem grep fallbacks:
+
+When `Graph files queried:` is `NONE`, a `- Justification:` line with a non-empty
+value is also required.
+
+A file is exempt if its first line is `<!-- graph-usage-report:skip -->`.
+
+Exit codes:
+  0 every input file is valid
+  1 any input file fails validation
+  2 usage error (no files supplied)
+EOF
+    exit 0
+fi
+
+if [ "$#" -lt 1 ]; then
+    echo "usage: $0 <file> [<file> ...]" >&2
+    exit 2
+fi
+
+REQUIRED_BULLETS=(
+    "- Graph files queried:"
+    "- Modules identified via graph:"
+    "- Files identified via graph:"
+    "- Filesystem grep fallbacks:"
+)
+
+fail=0
+
+for f in "$@"; do
+    if [ ! -f "$f" ]; then
+        echo "MISSING: $f does not exist" >&2
+        fail=1
+        continue
+    fi
+
+    if head -1 "$f" | grep -q '^<!-- graph-usage-report:skip -->'; then
+        continue
+    fi
+
+    if ! grep -q '^## Graph Usage Report' "$f"; then
+        echo "FAIL: $f — missing '## Graph Usage Report' section" >&2
+        fail=1
+        continue
+    fi
+
+    section_start=$(grep -n '^## Graph Usage Report' "$f" | head -1 | cut -d: -f1)
+    section_body=$(awk -v start="$section_start" 'NR > start { if (/^## /) exit; print }' "$f")
+
+    for bullet in "${REQUIRED_BULLETS[@]}"; do
+        if ! printf '%s\n' "$section_body" | grep -qF -- "$bullet"; then
+            echo "FAIL: $f — Graph Usage Report missing bullet: '$bullet'" >&2
+            fail=1
+        fi
+    done
+
+    if printf '%s\n' "$section_body" | grep -qE -- '^- Graph files queried:[[:space:]]*NONE'; then
+        if ! printf '%s\n' "$section_body" | grep -qE -- '^- Justification[^:]*:[[:space:]]*[^[:space:]]'; then
+            echo "FAIL: $f — 'Graph files queried: NONE' requires a populated Justification line" >&2
+            fail=1
+        fi
+    fi
+done
+
+exit "$fail"

package/scripts/tools/check-scope-conflicts.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# check-scope-conflicts.sh
+#
+# Walks every track in the repository (or those passed on the command line),
+# reads `scope_includes` / `scope_excludes` from metadata.json (preferred) or
+# the spec.md frontmatter (fallback), and flags any two tracks that share an
+# included scope tag without one excluding the other's tag set.
+#
+# Usage:
+# scripts/tools/check-scope-conflicts.sh # scan ./tracks/*
+# scripts/tools/check-scope-conflicts.sh tracks/foo tracks/bar
+# scripts/tools/check-scope-conflicts.sh --json ...
+#
+# Exit codes:
+# 0 no conflicts
+# 1 conflicts 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
+TRACK_PATHS=()
+
+usage() {
+    local stream=2 code=2
+    if [[ "${USAGE_HELP_MODE:-0}" == 1 ]]; then stream=1; code=0; fi
+    sed -n '2,17p' "$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 < <(discover_track_dirs "$REPO_ROOT")
+fi
+
+conflict_count=0
+declare -a conflicts=()
+declare -a track_rels=()
+declare -a track_includes=()
+declare -a track_excludes=()
+
+record() { conflicts+=("$1|$2|$3"); conflict_count=$((conflict_count + 1)); }
+
+for t in "${TRACK_PATHS[@]}"; do
+    [[ -d "$t" ]] || { record "$t" "not-a-directory" ""; continue; }
+    track_dir="$(cd "$t" && pwd)"
+    rel="${track_dir#"$REPO_ROOT/"}"
+    inc=""; exc=""
+    [[ -f "$track_dir/metadata.json" ]] && {
+        inc="$(read_scope_array "$track_dir/metadata.json" scope_includes)"
+        exc="$(read_scope_array "$track_dir/metadata.json" scope_excludes)"
+    }
+    if [[ -z "$inc" && -f "$track_dir/spec.md" ]]; then
+        inc="$(read_scope_array "$track_dir/spec.md" scope_includes)"
+        exc="$(read_scope_array "$track_dir/spec.md" scope_excludes)"
+    fi
+    track_rels+=("$rel")
+    track_includes+=("$inc")
+    track_excludes+=("$exc")
+done
+
+for ((i=0; i<${#track_rels[@]}; i++)); do
+    for ((j=i+1; j<${#track_rels[@]}; j++)); do
+        a="${track_rels[$i]}"
+        b="${track_rels[$j]}"
+        a_inc="${track_includes[$i]}"
+        b_inc="${track_includes[$j]}"
+        a_exc="${track_excludes[$i]}"
+        b_exc="${track_excludes[$j]}"
+        for tag in $a_inc; do
+            [[ -z "$tag" ]] && continue
+            if [[ " $b_inc " == *" $tag "* ]]; then
+                conflict=1
+                for ex in $a_exc; do
+                    [[ -z "$ex" ]] && continue
+                    if [[ " $b_inc " == *" $ex "* ]]; then conflict=0; break; fi
+                done
+                if ((conflict)); then
+                    for ex in $b_exc; do
+                        [[ -z "$ex" ]] && continue
+                        if [[ " $a_inc " == *" $ex "* ]]; then conflict=0; break; fi
+                    done
+                fi
+                if ((conflict)); then
+                    record "$a" "scope-conflict" "shares '$tag' with $b without mutual exclusion"
+                fi
+            fi
+        done
+    done
+done
+
+emit() {
+    if ((EMIT_JSON)); then
+        printf '{"conflict_count": %d, "conflicts": [\n' "$conflict_count"
+        local first=1 c track kind detail
+        for c in "${conflicts[@]}"; do
+            IFS='|' read -r track kind detail <<< "$c"
+            if ((first)); then first=0; else printf ',\n'; fi
+            printf ' {"track":"%s","kind":"%s","detail":"%s"}' \
+                "$(json_escape "$track")" "$(json_escape "$kind")" \
+                "$(json_escape "$detail")"
+        done
+        printf '\n]}\n'
+    else
+        if ((conflict_count == 0)); then
+            printf 'OK: no scope conflicts across %d track(s).\n' "${#TRACK_PATHS[@]}"
+        else
+            printf 'SCOPE: %d conflict(s) across %d track(s).\n' \
+                "$conflict_count" "${#TRACK_PATHS[@]}" >&2
+            local c track kind detail
+            for c in "${conflicts[@]}"; do
+                IFS='|' read -r track kind detail <<< "$c"
+                printf ' [%s] %s — %s\n' "$kind" "$track" "$detail" >&2
+            done
+        fi
+    fi
+}
+emit
+
+((conflict_count == 0))

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

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# check-skill-line-caps.sh
+#
+# Enforces per-skill line-count caps (WS-10 prompt-economy budget). Walks
+# skills/**/SKILL.md and reports any file whose line count exceeds its cap.
+# Caps are sourced from a config file (default scripts/tools/skill-caps.conf)
+# or the SKILL_CAPS env. A skill not listed inherits the GLOBAL_CAP default.
+#
+# Modes:
+# default warn-only (exit 0 regardless; report on stderr)
+# --enforce strict (exit 1 on any over-cap skill)
+#
+# Usage:
+# scripts/tools/check-skill-line-caps.sh # warn-only
+# scripts/tools/check-skill-line-caps.sh --enforce # strict
+# scripts/tools/check-skill-line-caps.sh --json
+#
+# Exit codes:
+# 0 clean (or warn-only mode regardless of findings)
+# 1 --enforce and at least one skill exceeds its cap
+# 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)"
+CAPS_CONF_DEFAULT="$SCRIPT_DIR/skill-caps.conf"
+
+EMIT_JSON=0
+ENFORCE=0
+CAPS_CONF="$CAPS_CONF_DEFAULT"
+SKILLS_DIR="$REPO_ROOT/skills"
+
+usage() {
+    local stream=2 code=2
+    if [[ "${USAGE_HELP_MODE:-0}" == 1 ]]; then stream=1; code=0; fi
+    sed -n '2,21p' "$0" >&$stream
+    exit "$code"
+}
+
+while (($#)); do
+    case "$1" in
+        -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 ;;
+        -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
+        *) printf 'Unexpected arg: %s\n' "$1" >&2; usage ;;
+    esac
+done
+
+GLOBAL_CAP=600
+over_count=0
+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")"
+    if (( lines > cap )); then
+        record "$name" "$lines" "$cap"
+    fi
+done < <(find "$SKILLS_DIR" -mindepth 2 -maxdepth 2 -name 'SKILL.md' | sort)
+
+emit() {
+    if ((EMIT_JSON)); then
+        printf '{"over_cap_count": %d, "global_cap": %d, "findings": [\n' \
+            "$over_count" "$GLOBAL_CAP"
+        local first=1 v name lines cap
+        for v in "${findings[@]}"; do
+            IFS='|' read -r name lines cap <<< "$v"
+            if ((first)); then first=0; else printf ',\n'; fi
+            printf ' {"skill":"%s","lines":%d,"cap":%d}' \
+                "$(json_escape "$name")" "$lines" "$cap"
+        done
+        printf '\n]}\n'
+    else
+        if ((over_count == 0)); then
+            printf 'OK: all skills within cap (default %d).\n' "$GLOBAL_CAP"
+            return
+        fi
+        local mode="warn-only" stream=stderr
+        ((ENFORCE)) && mode="enforced"
+        if ((ENFORCE)); then
+            printf 'SKILL-CAPS: %d skill(s) over cap (%s):\n' \
+                "$over_count" "$mode" >&2
+        else
+            printf 'SKILL-CAPS: %d skill(s) over cap (%s):\n' \
+                "$over_count" "$mode"
+        fi
+        local v name lines cap
+        for v in "${findings[@]}"; do
+            IFS='|' read -r name lines cap <<< "$v"
+            if ((ENFORCE)); then
+                printf ' %s: %d lines (cap %d)\n' "$name" "$lines" "$cap" >&2
+            else
+                printf ' %s: %d lines (cap %d)\n' "$name" "$lines" "$cap"
+            fi
+        done
+    fi
+}
+emit
+
+if ((ENFORCE && over_count > 0)); then exit 1; fi

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# check-template-noop.sh
+#
+# CI gate enforcing WS-0 contract: any commit that touches skills/** or
+# scripts/tools/** must also touch core/templates/**, or carry the literal
+# tag [template-noop] in the commit message.
+#
+# Rationale: skill-only or validator-only schema changes silently drift from
+# the templates. Forcing them to travel together (or explicitly opt out) keeps
+# templates as the single canonical schema source.
+#
+# Usage:
+# scripts/tools/check-template-noop.sh # HEAD vs HEAD~1
+# scripts/tools/check-template-noop.sh <base> # HEAD vs base
+# scripts/tools/check-template-noop.sh <base>..<head> # range form
+#
+# Exit codes:
+# 0 OK (no relevant changes, or templates also touched, or [template-noop])
+# 1 violation
+# 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
+
+BASE="${1:-HEAD~1}"
+RANGE="$BASE..HEAD"
+if [[ "$BASE" == *..* ]]; then
+    RANGE="$BASE"
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    printf 'check-template-noop: not inside a git repository\n' >&2
+    exit 2
+fi
+
+# Diff name-only across the range.
+changed_files="$(git diff --name-only "$RANGE" 2>/dev/null || true)"
+if [[ -z "$changed_files" ]]; then
+    printf 'check-template-noop: no changes in range %s\n' "$RANGE"
+    exit 0
+fi
+
+touches_skills_or_tools=0
+touches_templates=0
+
+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 ;;
+    esac
+done <<< "$changed_files"
+
+if ((touches_skills_or_tools == 0)); then
+    printf 'check-template-noop: no skills/** or scripts/tools/** changes in range %s\n' "$RANGE"
+    exit 0
+fi
+
+if ((touches_templates == 1)); then
+    printf 'check-template-noop: OK — skills/tools changes accompanied by core/templates/** changes.\n'
+    exit 0
+fi
+
+# Look for [template-noop] tag in any commit message in the range.
+commit_log="$(git log --format=%B "$RANGE" 2>/dev/null || true)"
+if printf '%s' "$commit_log" | grep -Fq '[template-noop]'; then
+    printf 'check-template-noop: OK — [template-noop] tag present in commit message.\n'
+    exit 0
+fi
+
+cat >&2 <<EOF
+check-template-noop: FAIL
+  Range: $RANGE
+  skills/** or scripts/tools/** changed without touching core/templates/**.
+  Either:
+    (a) update core/templates/* to reflect the schema change, or
+    (b) add [template-noop] to the commit message if this is intentionally a no-op
+        for the template schema (e.g. pure bug fix, refactor, perf improvement).
+EOF
+exit 1