@drafthq/draft 2.7.0

package/scripts/tools/diff-templates-vs-tracks.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# diff-templates-vs-tracks.sh
+#
+# Surface tracks whose artifact set drifts from the current template schema.
+# Used by WS-0 (Templates are the contract) and the deploy-checklist gate.
+#
+# Compares the file set + section headers + required-field count between
+# core/templates/ and each tracks/*/ directory passed on the command line
+# (or every tracks/* found under the current repo if no path is given).
+#
+# Exit codes:
+# 0 no drift
+# 1 drift detected (details on stderr)
+# 2 usage / runtime error
+#
+# Usage:
+# scripts/tools/diff-templates-vs-tracks.sh # scan ./tracks/*
+# scripts/tools/diff-templates-vs-tracks.sh tracks/foo bar/ # scan listed dirs
+# scripts/tools/diff-templates-vs-tracks.sh --json ... # JSON output
+#
+# Notes:
+# - "Drift" is a heuristic: missing required section headers, missing files,
+# or known-removed fields still present.
+# - Templates themselves are linted: a template that omits a header expected
+# by the contract is also flagged.
+
+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)"
+TEMPLATES_DIR="$REPO_ROOT/core/templates"
+
+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,22p' "$0" >&$stream
+    exit "$code"
+}
+
+# Argument parsing
+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
+
+# Expected artifact files per track (all required at 2.0)
+REQUIRED_FILES=(spec.md plan.md hld.md lld.md metadata.json discovery.md)
+
+# Expected required section headers per markdown file. These are heuristics —
+# present in templates at 2.0, must be present in any track that claims to
+# conform. Match is case-insensitive and treats hyphen-or-space as equivalent
+# so author-style variation (Mode Selection vs Mode-selection) doesn't trip
+# the validator. The canonical form is the form in core/templates/.
+required_headers_for() {
+    case "$1" in
+        spec.md)      printf '%s' 'Problem Statement|Requirements|Acceptance Criteria|Risk Assessment|Open Questions' ;;
+        plan.md)      printf '%s' 'Phase 0|Phase 1|Status Markers' ;;
+        hld.md)       printf '%s' 'Background|Requirements|High Level Design|Detailed Design|Dependencies|Checklist|Deployment|Observability' ;;
+        lld.md)       printf '%s' 'Background|Requirements|Low Level Design|Observability' ;;
+        discovery.md) printf '%s' 'Hotspots|Mode Selection|Open Questions|References' ;;
+        *)            printf '%s' '' ;;
+    esac
+}
+
+# Strings that were removed at 2.0 — should not appear in conforming tracks.
+REMOVED_FIELDS_RE='Author1|xxx@\.com|xxx@example\.com|^Status: \[x\] Complete$'
+
+drift_count=0
+declare -a drift_records=()
+
+record_drift() {
+    local track="$1" kind="$2" detail="$3"
+    drift_records+=("$track|$kind|$detail")
+    drift_count=$((drift_count + 1))
+}
+
+scan_track() {
+    local track_dir="$1"
+    local rel_track
+    rel_track="${track_dir#"$REPO_ROOT/"}"
+
+    for fname in "${REQUIRED_FILES[@]}"; do
+        if [[ ! -f "$track_dir/$fname" ]]; then
+            record_drift "$rel_track" "missing-file" "$fname"
+        fi
+    done
+
+    for fname in spec.md plan.md hld.md lld.md discovery.md; do
+        local fpath="$track_dir/$fname"
+        [[ -f "$fpath" ]] || continue
+        local pattern
+        pattern="$(required_headers_for "$fname")"
+        [[ -n "$pattern" ]] || continue
+        IFS='|' read -r -a heads <<< "$pattern"
+        for h in "${heads[@]}"; do
+            # Build a hyphen-or-space-tolerant regex: every literal space in
+            # the expected header may match `[ -]` in the actual header.
+            local h_flex="${h// /[ -]}"
+            # Case-insensitive (-i) substring match against an ATX header line.
+            if ! grep -Eiq "^#{1,6} +.*${h_flex}" "$fpath"; then
+                record_drift "$rel_track" "missing-header" "$fname:$h"
+            fi
+        done
+    done
+
+    while IFS= read -r f; do
+        local rel_file="${f#"$track_dir/"}"
+        if grep -nE "$REMOVED_FIELDS_RE" "$f" >/dev/null 2>&1; then
+            while IFS= read -r line; do
+                record_drift "$rel_track" "removed-field" "$rel_file:$line"
+            done < <(grep -nE "$REMOVED_FIELDS_RE" "$f" | head -5)
+        fi
+    done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
+}
+
+# Sanity-check templates themselves first.
+for fname in "${REQUIRED_FILES[@]}"; do
+    [[ -f "$TEMPLATES_DIR/$fname" ]] || record_drift "core/templates" "missing-template" "$fname"
+done
+
+for t in "${TRACK_PATHS[@]}"; do
+    [[ -d "$t" ]] || { record_drift "$t" "not-a-directory" ""; continue; }
+    scan_track "$(cd "$t" && pwd)"
+done
+
+emit_records() {
+    if ((EMIT_JSON)); then
+        printf '{"drift_count": %d, "records": [\n' "$drift_count"
+        local first=1
+        for r in "${drift_records[@]}"; do
+            local track kind detail
+            IFS='|' read -r track kind detail <<< "$r"
+            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 ((drift_count == 0)); then
+            printf 'OK: no drift across %d track(s).\n' "${#TRACK_PATHS[@]}"
+        else
+            printf 'DRIFT: %d defect(s) across %d track(s).\n' \
+                "$drift_count" "${#TRACK_PATHS[@]}" >&2
+            local r track kind detail
+            for r in "${drift_records[@]}"; do
+                IFS='|' read -r track kind detail <<< "$r"
+                printf ' [%s] %s — %s\n' "$kind" "$track" "$detail" >&2
+            done
+        fi
+    fi
+}
+
+emit_records
+
+((drift_count == 0))

package/scripts/tools/emit-skill-metrics.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# emit-skill-metrics.sh — Append a NDJSON metrics record to ~/.draft/metrics.jsonl
+#
+# Usage: emit-skill-metrics.sh <json-payload>
+# json-payload: a JSON object string (must be valid JSON, single line)
+#
+# Exit codes: always 0 (silent on all errors — never break the calling skill)
+# Concurrency: uses flock on the metrics file to prevent interleaved writes
+
+set -euo pipefail
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  cat <<'EOF'
+Usage: emit-skill-metrics.sh '<json-payload>'
+
+Appends a single NDJSON record to ~/.draft/metrics.jsonl with an injected
+"ts" field (ISO-8601 UTC). Concurrency-safe via flock. Silent on all errors —
+never fails the calling skill. Rotates the metrics file to the last 1000 lines
+when it exceeds 10MB.
+
+Example:
+  emit-skill-metrics.sh '{"skill":"review","verdict":"approve"}'
+
+Resolution (when invoked by a skill):
+  1. $DRAFT_PLUGIN_ROOT/scripts/tools/emit-skill-metrics.sh
+  2. $HOME/.claude/plugins/draft/scripts/tools/emit-skill-metrics.sh
+  3. $PWD/scripts/tools/emit-skill-metrics.sh
+
+Self-test: /draft:draft metrics-check
+EOF
+  exit 0
+fi
+
+METRICS_DIR="${HOME}/.draft"
+METRICS_FILE="${METRICS_DIR}/metrics.jsonl"
+LOCK_FILE="${METRICS_DIR}/metrics.lock"
+
+payload="${1:-}"
+
+# Validate that a payload was provided
+if [[ -z "${payload}" ]]; then
+  exit 0
+fi
+
+# Ensure the metrics directory exists (silent — never fail the caller)
+mkdir -p "${METRICS_DIR}" 2>/dev/null || exit 0
+
+# Append ISO timestamp to the payload and write under an exclusive lock
+# flock -x -w 2: acquire exclusive lock, wait up to 2 seconds, then give up
+(
+  flock -x -w 2 200 2>/dev/null || exit 0
+
+  # Inject timestamp into the payload using sed (avoids requiring jq)
+  # Assumes payload ends with '}' — insert timestamp field before closing brace
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "unknown")"
+  record="${payload%\}},\"ts\":\"${ts}\"}"
+  echo "${record}" >> "${METRICS_FILE}" 2>/dev/null || true
+
+  # Rotate when file exceeds 10MB: keep last 1000 lines.
+  # Cheap size check via `wc -c`; only invoke rotation when triggered.
+  if [[ -f "${METRICS_FILE}" ]]; then
+    size_bytes=$(wc -c < "${METRICS_FILE}" 2>/dev/null || echo 0)
+    if [[ "${size_bytes}" -gt 10485760 ]]; then
+      tail -n 1000 "${METRICS_FILE}" > "${METRICS_FILE}.tmp" 2>/dev/null \
+        && mv -f "${METRICS_FILE}.tmp" "${METRICS_FILE}" 2>/dev/null \
+        || rm -f "${METRICS_FILE}.tmp" 2>/dev/null
+    fi
+  fi
+
+) 200>"${LOCK_FILE}" 2>/dev/null || true
+

package/scripts/tools/fix-whitespace.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# fix-whitespace.sh — strip trailing whitespace and blank lines at EOF from
+# AI-generated markdown files.
+#
+# GitHub (and git --check) rejects commits with trailing whitespace or a blank
+# final line. This script normalises draft-generated markdown in-place before
+# the files are committed, preventing upload failures.
+#
+# Usage:
+# # Fix specific files:
+# scripts/tools/fix-whitespace.sh <file> [<file> ...]
+#
+# # Fix all markdown files in a track:
+# scripts/tools/fix-whitespace.sh --track <track_id>
+#
+# # Fix all draft-generated markdown in the repo (safe subset):
+# scripts/tools/fix-whitespace.sh --draft [<repo_root>]
+#
+# Exit codes:
+# 0 — success (all files normalised; prints list of changed files)
+# 1 — invocation error
+# 2 — one or more files could not be processed
+
+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=_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+usage() {
+    sed -n '2,/^[^#]/p' "$0" | grep '^#' | sed 's/^# \?//'
+}
+
+# Fix a single file in-place.
+# Returns: 0 if modified, 1 if already clean (exit code from the function,
+# not the script — caller decides whether to count it).
+fix_file() {
+    local file="$1"
+    if [[ ! -f "$file" ]]; then
+        echo " SKIP (not a file): $file" >&2
+        return 2
+    fi
+    if [[ ! -w "$file" ]]; then
+        echo " ERROR (not writable): $file" >&2
+        return 2
+    fi
+
+    local original
+    original="$(cat "$file")"
+
+    # 1. Strip trailing whitespace on every line (spaces and tabs).
+    # 2. Strip trailing blank lines at EOF, then add exactly one final newline.
+    local fixed
+    fixed="$(
+        printf '%s' "$original" \
+        | sed 's/[[:space:]]*$//' \
+        | sed -e :a -e '/^\n*$/{$d;N;ba}'
+    )"$'\n'
+
+    if [[ "$fixed" == "$original" ]]; then
+        return 1 # already clean
+    fi
+
+    local _tmp
+    _tmp="$(mktemp "${file}.XXXXXX")"
+    if printf '%s' "$fixed" > "$_tmp"; then
+        mv -f "$_tmp" "$file"
+    else
+        rm -f "$_tmp"
+        return 2
+    fi
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# Collect target files from arguments
+# ---------------------------------------------------------------------------
+
+TARGETS=()
+REPO_ROOT=""
+
+if [[ $# -eq 0 ]]; then
+    usage
+    exit 0
+fi
+
+case "$1" in
+    --track)
+        [[ $# -ge 2 ]] || { echo "ERROR: --track requires a track_id argument." >&2; exit 1; }
+        TRACK_ID="$2"
+        # Determine repo root: walk up from cwd until draft/ is found.
+        REPO_ROOT="$(pwd)"
+        while [[ ! -d "$REPO_ROOT/draft" && "$REPO_ROOT" != "/" ]]; do
+            REPO_ROOT="$(dirname "$REPO_ROOT")"
+        done
+        TRACK_DIR="$REPO_ROOT/draft/tracks/$TRACK_ID"
+        if [[ ! -d "$TRACK_DIR" ]]; then
+            echo "ERROR: track directory not found: $TRACK_DIR" >&2
+            exit 1
+        fi
+        while IFS= read -r -d '' f; do
+            TARGETS+=("$f")
+        done < <(find "$TRACK_DIR" -maxdepth 1 -name "*.md" -print0 | sort -z)
+        ;;
+    --draft)
+        REPO_ROOT="${2:-$(pwd)}"
+        while [[ ! -d "$REPO_ROOT/draft" && "$REPO_ROOT" != "/" ]]; do
+            REPO_ROOT="$(dirname "$REPO_ROOT")"
+        done
+        if [[ ! -d "$REPO_ROOT/draft" ]]; then
+            echo "ERROR: could not locate draft/ directory from: ${2:-$(pwd)}" >&2
+            exit 1
+        fi
+        # Safe subset: only files produced by draft skills.
+        while IFS= read -r -d '' f; do
+            TARGETS+=("$f")
+        done < <(
+            find "$REPO_ROOT/draft" \
+                -name "architecture.md" \
+                -o -name ".ai-context.md" \
+                -o -name ".ai-profile.md" \
+                -o -name "hld.md" \
+                -o -name "lld.md" \
+                -o -name "spec.md" \
+                -o -name "plan.md" \
+                -o -name "rca.md" \
+                -o -name "guardrails.md" \
+                -o -name "product.md" \
+                -o -name "tech-stack.md" \
+            | sort \
+            | tr '\n' '\0'
+        )
+        ;;
+    -h|--help)
+        usage
+        exit 0
+        ;;
+    -*)
+        echo "ERROR: unknown option: $1" >&2
+        exit 1
+        ;;
+    *)
+        TARGETS=("$@")
+        ;;
+esac
+
+if [[ ${#TARGETS[@]} -eq 0 ]]; then
+    echo "fix-whitespace: no files to process."
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Process files
+# ---------------------------------------------------------------------------
+
+CHANGED=()
+ERRORS=()
+
+for f in "${TARGETS[@]}"; do
+    rc=0
+    fix_file "$f" || rc=$?
+    case $rc in
+        0) CHANGED+=("$f") ;;
+        1) ;; # already clean — silent
+        *) ERRORS+=("$f") ;;
+    esac
+done
+
+if [[ ${#CHANGED[@]} -gt 0 ]]; then
+    echo "fix-whitespace: normalised ${#CHANGED[@]} file(s):"
+    for f in "${CHANGED[@]}"; do
+        echo " $f"
+    done
+fi
+
+if [[ ${#ERRORS[@]} -gt 0 ]]; then
+    echo "fix-whitespace: ERROR — could not process ${#ERRORS[@]} file(s):" >&2
+    for f in "${ERRORS[@]}"; do
+        echo " $f" >&2
+    done
+    exit 2
+fi
+

package/scripts/tools/freshness-check.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# freshness-check.sh — verify recorded file hashes against current contents.
+#
+# Input state file format (draft/.state/freshness.json):
+# {
+# "generated_at": "2026-04-22T10:00:00Z",
+# "files": [
+# {"path": "draft/architecture.md", "sha256": "abc..."},
+# ...
+# ]
+# }
+#
+# Emits:
+# {
+# "fresh": true|false,
+# "stale_files": ["..."],
+# "missing_files": ["..."],
+# "reason": "..."
+# }
+#
+# Usage:
+# scripts/tools/freshness-check.sh [--state PATH] [--root DIR]
+#
+# Exit codes: 0 fresh, 1 invocation error, 2 stale (still emits JSON).
+set -euo pipefail
+
+STATE_FILE=""
+ROOT="."
+
+usage() {
+    cat <<'EOF'
+freshness-check.sh — verify file hashes against a recorded state snapshot.
+
+Usage:
+  scripts/tools/freshness-check.sh [--state PATH] [--root DIR]
+
+Flags:
+  --state PATH Path to freshness JSON (default: <root>/draft/.state/freshness.json).
+  --root DIR Repository root to resolve file paths against (default: cwd).
+  --help Show this help.
+
+Output: JSON {fresh, stale_files, missing_files, reason}.
+Exit 0 fresh, 2 stale (still emits JSON), 1 invocation error.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --state) STATE_FILE="$2"; shift 2;;
+        --root) ROOT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+if [[ ! -d "$ROOT" ]]; then
+    echo "ERROR: --root '$ROOT' is not a directory" >&2
+    exit 1
+fi
+ROOT_ABS="$(cd "$ROOT" && pwd)"
+
+if [[ -z "$STATE_FILE" ]]; then
+    STATE_FILE="$ROOT_ABS/draft/.state/freshness.json"
+fi
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    esc="${STATE_FILE//\\/\\\\}"; esc="${esc//\"/\\\"}"
+    printf '{"fresh": false, "stale_files": [], "missing_files": [], "reason": "no state file at %s"}\n' "$esc"
+    exit 2
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+    echo "ERROR: jq is required" >&2
+    exit 1
+fi
+
+# hash calc: prefer sha256sum; fallback shasum -a 256
+sha256() {
+    local f="$1"
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$f" | awk '{print $1}'
+    elif command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$f" | awk '{print $1}'
+    else
+        return 1
+    fi
+}
+
+stale=()
+missing=()
+
+while IFS=$'\t' read -r path expected; do
+    [[ -z "$path" ]] && continue
+    full="$ROOT_ABS/$path"
+    if [[ ! -f "$full" ]]; then
+        missing+=("$path")
+        continue
+    fi
+    actual="$(sha256 "$full")"
+    if [[ "$actual" != "$expected" ]]; then
+        stale+=("$path")
+    fi
+done < <(jq -r '.files[]? | [.path, .sha256] | @tsv' "$STATE_FILE")
+
+fresh="true"
+reason=""
+if [[ ${#stale[@]} -gt 0 || ${#missing[@]} -gt 0 ]]; then
+    fresh="false"
+    reason="$([[ ${#stale[@]} -gt 0 ]] && echo "${#stale[@]} stale" || echo "")"
+    if [[ ${#missing[@]} -gt 0 ]]; then
+        if [[ -n "$reason" ]]; then reason="$reason, "; fi
+        reason="${reason}${#missing[@]} missing"
+    fi
+fi
+
+json_array() {
+    local arr=("$@")
+    if [[ ${#arr[@]} -eq 0 ]]; then
+        printf '[]'
+        return
+    fi
+    printf '['
+    local first=true
+    for x in "${arr[@]}"; do
+        if $first; then first=false; else printf ','; fi
+        # Escape quotes.
+        escaped="${x//\\/\\\\}"
+        escaped="${escaped//\"/\\\"}"
+        printf '"%s"' "$escaped"
+    done
+    printf ']'
+}
+
+printf '{"fresh":%s,"stale_files":%s,"missing_files":%s,"reason":"%s"}\n' \
+    "$fresh" \
+    "$(json_array "${stale[@]+"${stale[@]}"}")" \
+    "$(json_array "${missing[@]+"${missing[@]}"}")" \
+    "$reason"
+
+if [[ "$fresh" == "false" ]]; then
+    exit 2
+fi
+exit 0