@datafog/fogclaw 0.1.0

package/scripts/ci/he-runbooks-lint.sh

@@ -0,0 +1,445 @@
+#!/bin/bash
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# he-runbooks-lint.sh  --  Lint runbook frontmatter & content
+#
+# Exit codes: 0=OK, 1=FAIL, 2=config error
+# ---------------------------------------------------------------------------
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+DEFAULT_CONFIG_PATH="scripts/ci/he-docs-config.json"
+
+ERRORS=0
+WARNINGS=0
+
+# ── env helpers ────────────────────────────────────────────────────────────
+
+env_flag() {
+  local name="$1"
+  local default="${2:-0}"
+  local val="${!name:-$default}"
+  [[ "$val" == "1" ]]
+}
+
+# ── emit / annotate ───────────────────────────────────────────────────────
+
+gh_annotate() {
+  local level="$1" file="$2" title="$3" msg="$4"
+  if [[ -n "$file" ]]; then
+    echo "::${level} file=${file},title=${title}::${msg}"
+  else
+    echo "::${level} title=${title}::${msg}"
+  fi
+}
+
+emit() {
+  local level="$1" file="$2" title="$3" msg="$4"
+  gh_annotate "$level" "$file" "$title" "$msg"
+  local upper
+  upper="$(echo "$level" | tr '[:lower:]' '[:upper:]')"
+  echo "${upper}: ${msg}" >&2
+}
+
+emit_and_count() {
+  local level="$1" file="$2" title="$3" msg="$4"
+  if [[ "$level" == "error" ]]; then
+    (( ERRORS++ )) || true
+  else
+    (( WARNINGS++ )) || true
+  fi
+  emit "$level" "$file" "$title" "$msg"
+}
+
+# ── config ────────────────────────────────────────────────────────────────
+
+load_config() {
+  local config_rel="${HARNESS_DOCS_CONFIG:-$DEFAULT_CONFIG_PATH}"
+  local config_path="$REPO_ROOT/$config_rel"
+  if [[ ! -f "$config_path" ]]; then
+    echo "Error: he-runbooks-lint missing/invalid config: Missing config '${config_rel}'. Fix: create it (bootstrap should do this) or set HARNESS_DOCS_CONFIG." >&2
+    return 1
+  fi
+  # Validate it is a JSON object
+  if ! jq -e 'type == "object"' "$config_path" >/dev/null 2>&1; then
+    echo "Error: he-runbooks-lint missing/invalid config: Config must be a JSON object." >&2
+    return 1
+  fi
+  CONFIG_PATH="$config_path"
+}
+
+# ── frontmatter extraction ────────────────────────────────────────────────
+
+# Reads file, outputs the frontmatter block (lines between first --- and
+# second ---) to stdout. Returns 1 if no frontmatter found.
+extract_frontmatter() {
+  local file="$1"
+  local in_fm=0
+  local first_line=1
+  local block=""
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    if (( first_line )); then
+      first_line=0
+      if [[ "$trimmed" == "---" ]]; then
+        in_fm=1
+        continue
+      else
+        return 1
+      fi
+    fi
+    if (( in_fm )); then
+      if [[ "$trimmed" == "---" ]]; then
+        printf '%s' "$block"
+        return 0
+      fi
+      if [[ -n "$block" ]]; then
+        block="${block}"$'\n'"${line}"
+      else
+        block="${line}"
+      fi
+    fi
+  done < "$file"
+
+  # Reached EOF without closing ---
+  return 1
+}
+
+# ── frontmatter parsing ──────────────────────────────────────────────────
+
+# Sets global variables: FM_TITLE, FM_USE_WHEN, FM_CALLED_FROM (newline-
+# separated list), FM_KEYS (newline-separated list), FM_HAS_CALLED_FROM.
+parse_frontmatter() {
+  local block="$1"
+
+  FM_TITLE=""
+  FM_USE_WHEN=""
+  FM_CALLED_FROM=""
+  FM_KEYS=""
+  FM_HAS_CALLED_FROM=0
+
+  local lines=()
+  while IFS= read -r line; do
+    lines+=("$line")
+  done <<< "$block"
+
+  local i=0
+  local count=${#lines[@]}
+
+  while (( i < count )); do
+    local raw="${lines[$i]}"
+    local trimmed
+    trimmed="$(echo "$raw" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+    # skip blanks and comments
+    if [[ -z "$trimmed" || "$trimmed" == \#* ]]; then
+      (( i++ )) || true
+      continue
+    fi
+
+    # must contain a colon to be a key
+    if [[ "$trimmed" != *:* ]]; then
+      (( i++ )) || true
+      continue
+    fi
+
+    local key val
+    key="$(echo "$trimmed" | sed 's/:.*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    val="$(echo "$trimmed" | sed 's/^[^:]*://' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+    if [[ -n "$key" ]]; then
+      if [[ -n "$FM_KEYS" ]]; then
+        FM_KEYS="${FM_KEYS}"$'\n'"${key}"
+      else
+        FM_KEYS="$key"
+      fi
+    fi
+
+    if [[ "$key" == "title" ]]; then
+      FM_TITLE="$(echo "$val" | sed "s/^[[:space:]]*//;s/[[:space:]]*$//;s/^[\"']//;s/[\"']$//")"
+      (( i++ )) || true
+      continue
+    fi
+
+    if [[ "$key" == "use_when" ]]; then
+      FM_USE_WHEN="$(echo "$val" | sed "s/^[[:space:]]*//;s/[[:space:]]*$//;s/^[\"']//;s/[\"']$//")"
+      (( i++ )) || true
+      continue
+    fi
+
+    if [[ "$key" == "called_from" ]]; then
+      FM_HAS_CALLED_FROM=1
+      # Inline array form: [a, b, c]
+      if [[ "$val" == \[* ]]; then
+        parse_called_from_inline "$val"
+        (( i++ )) || true
+        continue
+      fi
+      # YAML list form
+      local items=""
+      (( i++ )) || true
+      while (( i < count )); do
+        local sub="${lines[$i]}"
+        local sub_trimmed
+        sub_trimmed="$(echo "$sub" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+        if [[ -z "$sub_trimmed" ]]; then
+          (( i++ )) || true
+          continue
+        fi
+        # If it looks like a new key (has colon, doesn't start with -)
+        if [[ "$sub_trimmed" == *:* && "$sub_trimmed" != -* ]]; then
+          break
+        fi
+        if [[ "$sub_trimmed" == -* ]]; then
+          local item
+          item="$(echo "$sub_trimmed" | sed 's/^-[[:space:]]*//' | sed "s/^[[:space:]]*//;s/[[:space:]]*$//;s/^[\"']//;s/[\"']$//")"
+          if [[ -n "$item" ]]; then
+            if [[ -n "$items" ]]; then
+              items="${items}"$'\n'"${item}"
+            else
+              items="$item"
+            fi
+          fi
+        fi
+        (( i++ )) || true
+      done
+      FM_CALLED_FROM="$items"
+      continue
+    fi
+
+    (( i++ )) || true
+  done
+}
+
+# Parses inline [a, b, c] into FM_CALLED_FROM (newline-separated).
+parse_called_from_inline() {
+  local val="$1"
+  FM_CALLED_FROM=""
+  # Strip outer brackets
+  local inner
+  inner="$(echo "$val" | sed 's/^[[:space:]]*\[//;s/\][[:space:]]*$//')"
+  inner="$(echo "$inner" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  if [[ -z "$inner" ]]; then
+    return
+  fi
+  local IFS=','
+  local parts
+  read -ra parts <<< "$inner"
+  for p in "${parts[@]}"; do
+    local trimmed
+    trimmed="$(echo "$p" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    if [[ -n "$trimmed" ]]; then
+      if [[ -n "$FM_CALLED_FROM" ]]; then
+        FM_CALLED_FROM="${FM_CALLED_FROM}"$'\n'"${trimmed}"
+      else
+        FM_CALLED_FROM="$trimmed"
+      fi
+    fi
+  done
+}
+
+# ── suspicious gate-waiver check ─────────────────────────────────────────
+
+# Checks file text for patterns that suggest waiving skill gates.
+# Sets SUSPICIOUS_MATCH to the matched snippet, or empty string.
+check_suspicious_gate_waiver() {
+  local file="$1"
+
+  SUSPICIOUS_MATCH=""
+
+  local patterns=(
+    '\b(skip|waive|override|ignore)\b.{0,80}\b(gate|review|verify|verify-release|security|data|tests?)\b'
+    '\b(disable|turn off)\b.{0,80}\b(tests?|checks?|ci)\b'
+    '\b(force merge|merge anyway|ignore failing)\b'
+  )
+
+  for pat in "${patterns[@]}"; do
+    local match=""
+    # Use grep -ioP for PCRE; fall back to grep -ioE
+    match="$(grep -ioP "$pat" "$file" 2>/dev/null | head -1)" || true
+    if [[ -z "$match" ]]; then
+      match="$(grep -ioE "$pat" "$file" 2>/dev/null | head -1)" || true
+    fi
+    if [[ -z "$match" ]]; then
+      continue
+    fi
+
+    # Find byte offset to check prefix for negation
+    local byte_offset=""
+    byte_offset="$(grep -iobP "$pat" "$file" 2>/dev/null | head -1 | cut -d: -f1)" || true
+    if [[ -z "$byte_offset" ]]; then
+      byte_offset="$(grep -iobE "$pat" "$file" 2>/dev/null | head -1 | cut -d: -f1)" || true
+    fi
+
+    if [[ -n "$byte_offset" ]] && (( byte_offset > 0 )); then
+      local prefix_start=$(( byte_offset > 40 ? byte_offset - 40 : 0 ))
+      local prefix_len=$(( byte_offset - prefix_start ))
+      local prefix
+      prefix="$(dd if="$file" bs=1 skip="$prefix_start" count="$prefix_len" 2>/dev/null | tr '[:upper:]' '[:lower:]')"
+      # Check negation prefixes
+      local negated=0
+      for neg in "do not" "don't" "must not" "never" "cannot" "can't" "should not"; do
+        if [[ "$prefix" == *"$neg"* ]]; then
+          negated=1
+          break
+        fi
+      done
+      if (( negated )); then
+        continue
+      fi
+    fi
+
+    # Clean up the snippet
+    local snippet
+    snippet="$(echo "$match" | tr '\n' ' ' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    SUSPICIOUS_MATCH="$snippet"
+    return 0
+  done
+
+  return 1
+}
+
+# ── lint a single runbook ─────────────────────────────────────────────────
+
+lint_runbook() {
+  local path="$1"
+  local fail_missing_called_from="$2"
+  local fail_extra_keys="$3"
+
+  local rel="${path#"$REPO_ROOT/"}"
+  local strict=0
+  env_flag "HARNESS_STRICT_RUNBOOKS" "0" && strict=1 || true
+
+  # --- frontmatter presence ---
+  local block=""
+  if ! block="$(extract_frontmatter "$path")"; then
+    local level="warning"
+    (( strict )) && level="error"
+    emit_and_count "$level" "$rel" "Runbook frontmatter" \
+      "Runbook '${rel}' must start with YAML frontmatter ('---')."
+    return
+  fi
+
+  # --- parse ---
+  parse_frontmatter "$block"
+
+  # --- required fields ---
+  if [[ -z "$FM_TITLE" ]]; then
+    local level="warning"
+    (( strict )) && level="error"
+    emit_and_count "$level" "$rel" "Runbook frontmatter" \
+      "Runbook '${rel}' frontmatter must include a 'title:' field."
+  fi
+
+  if [[ -z "$FM_USE_WHEN" ]]; then
+    local level="warning"
+    (( strict )) && level="error"
+    emit_and_count "$level" "$rel" "Runbook frontmatter" \
+      "Runbook '${rel}' frontmatter must include a 'use_when:' field."
+  fi
+
+  # --- called_from ---
+  if (( ! FM_HAS_CALLED_FROM )) || [[ -z "$FM_CALLED_FROM" ]]; then
+    local level="warning"
+    if (( strict )) || [[ "$fail_missing_called_from" == "1" ]]; then
+      level="error"
+    fi
+    emit_and_count "$level" "$rel" "Runbook frontmatter" \
+      "Runbook '${rel}' frontmatter should include non-empty 'called_from:' (list of skills/steps where this runbook is applied)."
+  fi
+
+  # --- extra keys ---
+  local extras=""
+  if [[ -n "$FM_KEYS" ]]; then
+    while IFS= read -r k; do
+      if [[ "$k" != "title" && "$k" != "use_when" && "$k" != "called_from" ]]; then
+        if [[ -n "$extras" ]]; then
+          extras="${extras}, ${k}"
+        else
+          extras="$k"
+        fi
+      fi
+    done <<< "$FM_KEYS"
+  fi
+
+  if [[ -n "$extras" ]]; then
+    local level="warning"
+    if (( strict )) || [[ "$fail_extra_keys" == "1" ]]; then
+      level="error"
+    fi
+    emit_and_count "$level" "$rel" "Runbook frontmatter" \
+      "Runbook '${rel}' has extra frontmatter key(s): ${extras}. Prefer keeping runbooks to {title,use_when,called_from} unless you have a strong reason."
+  fi
+
+  # --- suspicious gate-waiver language ---
+  if check_suspicious_gate_waiver "$path"; then
+    local level="warning"
+    (( strict )) && level="error"
+    emit_and_count "$level" "$rel" "Potential gate waiver" \
+      "Runbook '${rel}' appears to suggest waiving skill-enforced gates: '${SUSPICIOUS_MATCH}'. Runbooks are additive only; skill gates win."
+  fi
+}
+
+# ── iter_runbooks ─────────────────────────────────────────────────────────
+
+iter_runbooks() {
+  local dir="$1"
+  if [[ ! -d "$dir" ]]; then
+    return
+  fi
+  find "$dir" -name '*.md' -type f | sort
+}
+
+# ── main ──────────────────────────────────────────────────────────────────
+
+main() {
+  if ! load_config; then
+    return 2
+  fi
+
+  local fail_missing_called_from=0
+  env_flag "HARNESS_FAIL_ON_MISSING_RUNBOOK_CALLED_FROM" "0" && fail_missing_called_from=1 || true
+
+  local fail_extra_keys=0
+  env_flag "HARNESS_FAIL_ON_EXTRA_RUNBOOK_FRONTMATTER" "0" && fail_extra_keys=1 || true
+
+  local runbooks_dir="$REPO_ROOT/docs/runbooks"
+
+  echo "he-runbooks-lint: starting"
+  echo "Repro: bash scripts/ci/he-runbooks-lint.sh"
+
+  # --- expected runbooks from config ---
+  local expected_runbooks
+  expected_runbooks="$(jq -r '(.expected_runbooks // .required_runbooks // []) | if type == "array" then .[] else empty end' "$CONFIG_PATH" 2>/dev/null)" || true
+
+  if [[ -n "$expected_runbooks" ]]; then
+    while IFS= read -r rb; do
+      [[ -z "$rb" ]] && continue
+      if [[ ! -f "$REPO_ROOT/$rb" ]]; then
+        emit_and_count "warning" "$rb" "Expected runbook missing" \
+          "Missing runbook: '${rb}'. Policy: runbooks are additive and should not block forward progress. Fix: create it (run he-bootstrap) or remove it from expected_runbooks in config."
+      fi
+    done <<< "$expected_runbooks"
+  fi
+
+  # --- lint each runbook ---
+  while IFS= read -r path; do
+    [[ -z "$path" ]] && continue
+    lint_runbook "$path" "$fail_missing_called_from" "$fail_extra_keys"
+  done < <(iter_runbooks "$runbooks_dir")
+
+  # --- summary ---
+  if (( ERRORS > 0 )); then
+    echo "he-runbooks-lint: FAIL (${ERRORS} error(s), ${WARNINGS} warning(s))" >&2
+    return 1
+  fi
+
+  echo "he-runbooks-lint: OK (${WARNINGS} warning(s))"
+  return 0
+}
+
+main "$@"

package/scripts/ci/he-specs-lint.sh

@@ -0,0 +1,258 @@
+#!/bin/bash
+set -euo pipefail
+
+# ── Repo root relative to script location (scripts/ci/he-specs-lint.sh) ──
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DEFAULT_CONFIG_PATH="scripts/ci/he-docs-config.json"
+
+# ── Default required headings ──
+DEFAULT_REQUIRED_HEADINGS=(
+  "## Purpose / Big Picture"
+  "## Scope"
+  "## Non-Goals"
+  "## Risks"
+  "## Rollout"
+  "## Validation and Acceptance Signals"
+  "## Requirements"
+  "## Success Criteria"
+  "## Priority"
+  "## Initial Milestone Candidates"
+  "## Revision Notes"
+)
+
+DEFAULT_TRIVIAL_REQUIRED_HEADINGS=(
+  "## Purpose / Big Picture"
+  "## Requirements"
+  "## Success Criteria"
+)
+
+# ── Counters ──
+errors=0
+warnings=0
+
+# ── Helpers ──
+
+gh_annotate() {
+  local level="$1" file="$2" title="$3" msg="$4"
+  if [[ -n "$file" ]]; then
+    echo "::${level} file=${file},title=${title}::${msg}"
+  else
+    echo "::${level} title=${title}::${msg}"
+  fi
+}
+
+emit() {
+  local level="$1" file="$2" title="$3" msg="$4"
+  gh_annotate "$level" "$file" "$title" "$msg"
+  local upper
+  upper="$(echo "$level" | tr '[:lower:]' '[:upper:]')"
+  echo "${upper}: ${msg}" >&2
+  if [[ "$level" == "error" ]]; then
+    (( errors++ )) || true
+  else
+    (( warnings++ )) || true
+  fi
+}
+
+# Extract frontmatter block (content between first --- and second ---).
+# Returns via stdout; returns 1 if no valid frontmatter found.
+extract_frontmatter() {
+  local file="$1"
+  local first_line
+  first_line="$(head -n1 "$file")"
+  # Trim whitespace
+  first_line="$(echo "$first_line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  if [[ "$first_line" != "---" ]]; then
+    return 1
+  fi
+  # Print lines between first --- and second ---, exclusive
+  awk 'NR==1 && /^[[:space:]]*---[[:space:]]*$/ { found=1; next }
+       found && /^[[:space:]]*---[[:space:]]*$/ { exit }
+       found { print }' "$file"
+  # Verify we actually found a closing ---
+  local count
+  count="$(awk '/^[[:space:]]*---[[:space:]]*$/ { c++ } c==2 { print c; exit }' "$file")"
+  if [[ "$count" != "2" ]]; then
+    return 1
+  fi
+  return 0
+}
+
+# Parse frontmatter key-value pairs into an associative array.
+# Usage: parse_frontmatter "$frontmatter_text"
+# Sets global associative array FM_KV.
+parse_frontmatter() {
+  local fm_text="$1"
+  FM_KV=()
+  while IFS= read -r raw_line; do
+    # Trim
+    local line
+    line="$(echo "$raw_line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    # Skip empty lines and comments
+    [[ -z "$line" || "$line" == \#* ]] && continue
+    # Must contain a colon
+    [[ "$line" != *:* ]] && continue
+    local key val
+    key="$(echo "$line" | cut -d: -f1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    val="$(echo "$line" | cut -d: -f2- | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    FM_KV["$key"]="$val"
+  done <<< "$fm_text"
+}
+
+# Check if file contains an exact line match.
+has_exact_line() {
+  local file="$1" needle="$2"
+  grep -qFx "$needle" "$file"
+}
+
+# Check for placeholder tokens in file text.
+check_placeholders() {
+  local file_rel="$1" file_path="$2" fail_ph="$3"
+  shift 3
+  local patterns=("$@")
+  for p in "${patterns[@]}"; do
+    [[ -z "$p" ]] && continue
+    if grep -qF "$p" "$file_path"; then
+      local msg="Spec '${file_rel}' contains placeholder token '${p}'."
+      if [[ "$fail_ph" == "1" ]]; then
+        emit "error" "$file_rel" "Placeholder token" "$msg"
+      else
+        emit "warning" "$file_rel" "Placeholder token" "${msg} (Set HARNESS_FAIL_ON_ARTIFACT_PLACEHOLDERS=1 to enforce.)"
+      fi
+      break
+    fi
+  done
+}
+
+# ── Load config ──
+load_config() {
+  local config_rel="${HARNESS_DOCS_CONFIG:-$DEFAULT_CONFIG_PATH}"
+  local config_path="${REPO_ROOT}/${config_rel}"
+  if [[ ! -f "$config_path" ]]; then
+    echo "Error: he-specs-lint missing/invalid config: Missing config '${config_rel}'. Fix: create it (bootstrap should do this) or set HARNESS_DOCS_CONFIG." >&2
+    exit 2
+  fi
+  # Validate it's a JSON object
+  if ! jq -e 'type == "object"' "$config_path" > /dev/null 2>&1; then
+    echo "Error: he-specs-lint missing/invalid config: Config must be a JSON object." >&2
+    exit 2
+  fi
+  CONFIG_PATH="$config_path"
+}
+
+# ── Check a single spec file ──
+check_spec() {
+  local file_path="$1"
+  local rel="${file_path#"${REPO_ROOT}"/}"
+
+  # Extract frontmatter
+  local fm_text
+  if ! fm_text="$(extract_frontmatter "$file_path")"; then
+    emit "error" "$rel" "Missing YAML frontmatter" \
+      "Spec '${rel}' must start with YAML frontmatter delimited by '---' lines."
+    return
+  fi
+
+  # Parse frontmatter key-value pairs
+  declare -A FM_KV
+  parse_frontmatter "$fm_text"
+
+  # Required frontmatter keys from config
+  local required_keys_json
+  required_keys_json="$(jq -r '(.required_spec_frontmatter_keys // []) | if type == "array" then .[] else empty end' "$CONFIG_PATH" 2>/dev/null)" || true
+  if [[ -n "$required_keys_json" ]]; then
+    while IFS= read -r k; do
+      [[ -z "$k" ]] && continue
+      if [[ -z "${FM_KV[$k]+x}" ]]; then
+        emit "error" "$rel" "Missing frontmatter key" \
+          "Spec '${rel}' missing YAML frontmatter key '${k}:'."
+      fi
+    done <<< "$required_keys_json"
+  fi
+
+  # Validate plan_mode
+  local plan_mode="${FM_KV[plan_mode]:-}"
+  plan_mode="$(echo "$plan_mode" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  if [[ -n "$plan_mode" && "$plan_mode" != "trivial" && "$plan_mode" != "lightweight" && "$plan_mode" != "execution" ]]; then
+    emit "error" "$rel" "Invalid plan_mode" \
+      "Spec '${rel}' has invalid plan_mode '${plan_mode}' (must be 'trivial', 'lightweight', or 'execution')."
+  fi
+
+  # Validate spike_recommended
+  local spike_rec="${FM_KV[spike_recommended]:-}"
+  spike_rec="$(echo "$spike_rec" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  if [[ -n "$spike_rec" && "$spike_rec" != "yes" && "$spike_rec" != "no" ]]; then
+    emit "error" "$rel" "Invalid spike_recommended" \
+      "Spec '${rel}' has invalid spike_recommended '${spike_rec}' (must be 'yes' or 'no')."
+  fi
+
+  # Required headings
+  local -a required_headings
+  if [[ "$plan_mode" == "trivial" ]]; then
+    required_headings=("${DEFAULT_TRIVIAL_REQUIRED_HEADINGS[@]}")
+  else
+    required_headings=("${DEFAULT_REQUIRED_HEADINGS[@]}")
+  fi
+  for h in "${required_headings[@]}"; do
+    if ! has_exact_line "$file_path" "$h"; then
+      emit "error" "$rel" "Missing heading" \
+        "Spec '${rel}' missing required heading line '${h}'."
+    fi
+  done
+
+  # Placeholder patterns
+  local -a placeholder_patterns=()
+  local patterns_json
+  patterns_json="$(jq -r '(.artifact_placeholder_patterns // []) | if type == "array" then .[] else empty end' "$CONFIG_PATH" 2>/dev/null)" || true
+  if [[ -n "$patterns_json" ]]; then
+    while IFS= read -r p; do
+      [[ -n "$p" ]] && placeholder_patterns+=("$p")
+    done <<< "$patterns_json"
+  fi
+
+  local fail_ph="${HARNESS_FAIL_ON_ARTIFACT_PLACEHOLDERS:-0}"
+  if [[ ${#placeholder_patterns[@]} -gt 0 ]]; then
+    check_placeholders "$rel" "$file_path" "$fail_ph" "${placeholder_patterns[@]}"
+  fi
+}
+
+# ── Main ──
+main() {
+  load_config
+
+  echo "he-specs-lint: starting"
+  echo "Repro: bash scripts/ci/he-specs-lint.sh"
+
+  local specs_dir="${REPO_ROOT}/docs/specs"
+  if [[ ! -d "$specs_dir" ]]; then
+    echo "he-specs-lint: OK (docs/specs not present)"
+    exit 0
+  fi
+
+  # Collect spec files (*.md excluding README.md and index.md), sorted
+  local -a files=()
+  while IFS= read -r -d '' f; do
+    local basename
+    basename="$(basename "$f")"
+    [[ "$basename" == "README.md" || "$basename" == "index.md" ]] && continue
+    files+=("$f")
+  done < <(find "$specs_dir" -maxdepth 1 -name '*.md' -print0 | sort -z)
+
+  if [[ ${#files[@]} -eq 0 ]]; then
+    echo "he-specs-lint: OK (no spec files)"
+    exit 0
+  fi
+
+  for f in "${files[@]}"; do
+    check_spec "$f"
+  done
+
+  if [[ $errors -gt 0 ]]; then
+    echo "he-specs-lint: FAIL (${errors} error(s), ${warnings} warning(s))" >&2
+    exit 1
+  fi
+  echo "he-specs-lint: OK (${warnings} warning(s))"
+  exit 0
+}
+
+main "$@"