jekyll-theme-zer0 1.28.0 → 1.30.0

data/scripts/content-review.rb

@@ -348,7 +348,26 @@ def check_quality(body, quality)
 
   # Bare URLs.
   if quality['flag_bare_urls']
-    bare = strip_code_fences(body).scan(%r{(?<![("<\]])\bhttps?://[^\s)>\]]+}).reject { |u| u.include?('](') }
+    # Two sources of false positives this guards against:
+    #   [http://x](http://x) — a CORRECT markdown link whose text is the URL.
+    #     The lookbehind must exclude `[` too, or the link text is counted.
+    #   <script>/<style> blocks and HTML attributes — pages that embed a config
+    #     generator carry URLs in JS strings and markup, which are code, not prose.
+    #   <code>http://…</code> — inline code in HTML syntax, which the markdown
+    #     backtick form is already exempt from; the two should agree.
+    # Stripping markup in ONE pass leaves split or nested tags behind (CodeQL:
+    # incomplete multi-character sanitization). This is prose extraction for
+    # counting, never sanitization for output, but iterate to a fixpoint anyway
+    # so the result is exact. Each pass strictly shortens the string, so it
+    # terminates.
+    prose = strip_code_fences(body)
+    loop do
+      before = prose
+      prose = prose.gsub(%r{<(script|style|code|pre)\b[^>]*>.*?</\1\s*>}mi, ' ')
+                   .gsub(/<[^<>]*>/, ' ')
+      break if prose == before
+    end
+    bare = prose.scan(%r{(?<![("<\[\]])\bhttps?://[^\s)>\]]+}).reject { |u| u.include?('](') }
     issues << Issue.new('info', 'quality', "#{bare.length} bare URL(s) — wrap as [text](url)") unless bare.empty?
   end
   issues

data/scripts/design-system-check.rb

@@ -0,0 +1,170 @@
+#!/usr/bin/env ruby
+# Feature: ZER0-081
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# design-system-check — token parity between the theme and its Claude Design
+# mirror.
+#
+# The `--zer0-*` design tokens live twice on purpose:
+#   - `_sass/tokens/*.scss`         — the source of truth the theme compiles
+#   - `_design-system/tokens/*.css` — the mirror pushed to the Claude Design
+#                                     project (see _design-system/SYNC.md)
+#
+# This check keeps the two in lockstep so the design system can be built from
+# either side without silent drift:
+#
+#   1. Per file pair: the sets of `--zer0-*` names must match, and every value
+#      must resolve to the same string. `var(--x, fallback)` wrappers are
+#      resolved against the mirror's concrete `--bs-*`/`--bd-*` primitives, so
+#      the theme's alias form and the mirror's self-contained form compare
+#      equal.
+#   2. Skins: `_sass/theme/_skins.scss` and `tokens/skins.css` must declare the
+#      same skin names, and each mirror skin's brand hex must appear in the
+#      matching SCSS block.
+#   3. Dangling-token audit: any fallback-less `var(--zer0-…)` reference in
+#      `_sass/` must be declared somewhere (tokens, includes, or JS).
+#
+#   ruby scripts/design-system-check.rb        # exit 1 + report on drift
+#
+# Runs in the `core` test suite (test/test_core.sh). Plain Ruby, no gems.
+# ---------------------------------------------------------------------------
+
+ROOT = File.expand_path('..', __dir__)
+
+PAIRS = {
+  '_sass/tokens/_color.scss'       => '_design-system/tokens/colors.css',
+  '_sass/tokens/_spacing.scss'     => '_design-system/tokens/spacing.css',
+  '_sass/tokens/_radius.scss'      => '_design-system/tokens/radius.css',
+  '_sass/tokens/_typography.scss'  => '_design-system/tokens/typography.css',
+  '_sass/tokens/_shadow.scss'      => '_design-system/tokens/shadows.css',
+  '_sass/tokens/_motion.scss'      => '_design-system/tokens/motion.css',
+  '_sass/tokens/_breakpoints.scss' => '_design-system/tokens/breakpoints.css',
+  '_sass/tokens/_layers.scss'      => '_design-system/tokens/layers.css'
+}.freeze
+
+SKIN_SCSS = '_sass/theme/_skins.scss'
+SKIN_CSS  = '_design-system/tokens/skins.css'
+
+def read(rel)
+  path = File.join(ROOT, rel)
+  abort "design-system-check: missing file #{rel}" unless File.file?(path)
+  File.read(path)
+end
+
+# Strip /* */ blocks, // line comments, and everything from the first @media on
+# (motion files re-declare durations under prefers-reduced-motion).
+def strip(text, scss:)
+  t = text.split('@media', 2).first
+  t = t.gsub(%r{/\*.*?\*/}m, '')
+  t = t.gsub(%r{(?:^|\s)//.*$}, '') if scss
+  t
+end
+
+# { '--zer0-foo' => 'raw value', ... } from declaration-position matches.
+def declarations(text)
+  text.scan(/(--zer0-[\w-]+)\s*:\s*([^;]+);/).each_with_object({}) do |(k, v), h|
+    h[k] ||= v.strip.gsub(/\s+/, ' ')
+  end
+end
+
+# All custom properties (any prefix) declared in the mirror's colors.css light
+# scope — the concrete primitives var() chains resolve against.
+def primitives
+  light = read(SKIN_CSS.sub('skins', 'colors')).split('[data-bs-theme="dark"]', 2).first
+  strip(light, scss: false).scan(/(--[\w-]+)\s*:\s*([^;]+);/)
+                           .each_with_object({}) { |(k, v), h| h[k] ||= v.strip.gsub(/\s+/, ' ') }
+end
+
+# Resolve a value that is entirely a var() wrapper: prefer the primitive's
+# concrete value, else the wrapper's own fallback. Inner var() references in
+# composite values (color-mix, rgba) are left as-is and compared literally.
+def resolve(value, prims, depth = 0)
+  v = value.strip.gsub(/\s+/, ' ')
+  return v if depth > 6
+
+  m = v.match(/\Avar\((--[\w-]+)(?:\s*,\s*(.+))?\)\z/)
+  return v unless m
+
+  name, fallback = m[1], m[2]
+  if prims.key?(name)
+    resolve(prims[name], prims, depth + 1)
+  elsif fallback
+    resolve(fallback, prims, depth + 1)
+  else
+    v
+  end
+end
+
+failures = []
+prims = primitives
+
+# --- 1. token parity per file pair -----------------------------------------
+PAIRS.each do |scss_rel, css_rel|
+  scss = declarations(strip(read(scss_rel), scss: true))
+  css  = declarations(strip(read(css_rel),  scss: false))
+
+  (scss.keys - css.keys).each { |k| failures << "#{css_rel}: missing #{k} (declared in #{scss_rel})" }
+  (css.keys - scss.keys).each { |k| failures << "#{scss_rel}: missing #{k} (declared in #{css_rel})" }
+
+  (scss.keys & css.keys).each do |k|
+    a = resolve(scss[k], prims)
+    b = resolve(css[k], prims)
+    failures << "#{k}: theme resolves to `#{a}` but mirror to `#{b}`" unless a == b
+  end
+end
+
+# Both motion files must keep the reduced-motion guard.
+[PAIRS.key('_design-system/tokens/motion.css'), '_design-system/tokens/motion.css'].each do |rel|
+  failures << "#{rel}: lost its prefers-reduced-motion guard" unless read(rel).include?('prefers-reduced-motion')
+end
+
+# --- 2. skins: same names, same brand hex ----------------------------------
+scss_skins_src = read(SKIN_SCSS)
+css_skins_src  = read(SKIN_CSS)
+scss_skins = scss_skins_src.scan(/\[data-theme-skin="(\w+)"\]/).flatten.uniq.sort
+css_skins  = css_skins_src.scan(/\[data-theme-skin="(\w+)"\]/).flatten.uniq.sort
+unless scss_skins == css_skins
+  failures << "skins differ: theme has #{scss_skins.join(', ')} but mirror has #{css_skins.join(', ')}"
+end
+
+(scss_skins & css_skins).each do |skin|
+  block = css_skins_src[/\[data-theme-skin="#{skin}"\]\s*\{.*?\}/m].to_s
+  hex = block[/--zer0-color-primary:\s*(#\h+)/, 1]
+  next unless hex
+
+  scss_block = scss_skins_src[/\[data-theme-skin="#{skin}"\]\s*\{.*?\}/m].to_s
+  unless scss_block.downcase.include?(hex.downcase)
+    failures << "skin #{skin}: mirror brand #{hex} not found in #{SKIN_SCSS}"
+  end
+end
+
+# --- 3. dangling-token audit ------------------------------------------------
+declared = Dir.glob(File.join(ROOT, '_sass/**/*.scss'))
+              .flat_map { |f| File.read(f).scan(/(--zer0-[\w-]+)\s*:/) }.flatten
+declared += Dir.glob(File.join(ROOT, '{_includes,_layouts}/**/*.html'))
+               .flat_map { |f| File.read(f).scan(/(--zer0-[\w-]+)\s*:/) }.flatten
+declared += Dir.glob(File.join(ROOT, 'assets/js/**/*.js')).flat_map do |f|
+  src = File.read(f)
+  src.scan(/setProperty\(\s*['"](--zer0-[\w-]+)/).flatten +
+    src.scan(/['"`](--zer0-[\w-]+)['"`:]/).flatten
+end
+declared = declared.uniq
+
+Dir.glob(File.join(ROOT, '_sass/**/*.scss')).sort.each do |f|
+  File.read(f).scan(/var\(\s*(--zer0-[\w-]+)\s*\)/).flatten.uniq.each do |token|
+    next if declared.include?(token)
+
+    failures << "#{f.sub("#{ROOT}/", '')}: references #{token} with no fallback, but it is never declared"
+  end
+end
+
+# --- report -----------------------------------------------------------------
+if failures.empty?
+  puts "design-system-check: OK — #{PAIRS.size} token file pairs, #{css_skins.size} skins, no dangling tokens"
+else
+  warn "design-system-check: #{failures.size} problem(s) — theme (_sass/tokens) and mirror (_design-system/tokens) have drifted:"
+  failures.each { |f| warn "  - #{f}" }
+  warn 'Fix the drift (see _design-system/SYNC.md), then re-run: ruby scripts/design-system-check.rb'
+  exit 1
+end

data/scripts/lib/audit.sh

@@ -205,13 +205,45 @@ detect_consumer_mode() {
         return
     fi
 
-    if grep -qE '^remote_theme:' "$config"; then
+    # Match a top-level `remote_theme` key. The whitespace class before the
+    # colon is load-bearing: most fleet consumers write column-aligned YAML
+    # (`remote_theme             : "bamr87/zer0-mistakes"`), which a bare
+    # `^remote_theme:` never matches — every one of them was silently
+    # misreported as gem mode, skipping the plugin checks entirely.
+    # `|| true` keeps a no-match grep from tripping the caller's `set -o pipefail`.
+    local line value
+    line=$(grep -m1 -E '^remote_theme[[:space:]]*:' "$config" 2>/dev/null || true)
+    value=$(printf '%s' "$line" \
+            | sed -E 's/^remote_theme[[:space:]]*:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^"(.*)"$/\1/; s/^'\''(.*)'\''$/\1/')
+
+    # `remote_theme: false` (or an empty value) is how a consumer turns the
+    # remote theme OFF and resolves the theme as a gem instead.
+    if [[ -n "$value" && "$value" != "false" ]]; then
         echo "remote_theme"
     else
         echo "gem"
     fi
 }
 
+# detect_consumer_source <consumer_root>
+# Echoes the Jekyll `source:` value from _config.yml (relative path), or empty.
+#
+# Jekyll's `source:` relocates the whole site tree — zer0-pages keeps every
+# theme-shadowing file under `pages/`. Auditing the repo root there reports a
+# falsely clean "0 overrides, 0 unique files"; the real surface only appears
+# when the scan follows `source:`.
+detect_consumer_source() {
+    local consumer_root="$1"
+    local config="$consumer_root/_config.yml"
+
+    [[ -f "$config" ]] || return 0
+
+    local line
+    line=$(grep -m1 -E '^source[[:space:]]*:' "$config" 2>/dev/null || true)
+    printf '%s' "$line" \
+        | sed -E 's/^source[[:space:]]*:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^"(.*)"$/\1/; s/^'\''(.*)'\''$/\1/; s#^\./##; s#/$##'
+}
+
 # ---------------------------------------------------------------------------
 # Output helpers
 # ---------------------------------------------------------------------------
@@ -277,7 +309,15 @@ print_classification() {
                 echo "::notice file=$relpath::OPTIONAL_PLUGIN (not required)" ;;
         esac
     elif [[ "$format" == "json" ]]; then
-        echo "  {\"path\":\"$relpath\",\"status\":\"$classification\"},"
+        # Separator goes BEFORE each entry but the first, so the array never
+        # ends on a dangling comma. Emitting a trailing comma per entry (the
+        # previous behaviour) produced `...},\n]}` — which no JSON parser
+        # accepts, making --format json unusable for any CI consumer.
+        if [[ "${JSON_ENTRY_EMITTED:-0}" == "1" ]]; then
+            printf ',\n'
+        fi
+        JSON_ENTRY_EMITTED=1
+        printf '  {"path":"%s","status":"%s"}' "$relpath" "$classification"
     else
         echo -e "${color}[$classification]${NC} $relpath"
     fi

data/scripts/lint-liquid-raw.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# lint-liquid-raw — guard the Markdown the Pages build renders through Liquid
+#
+# `github-pages` ships jekyll-optional-front-matter, so EVERY non-excluded
+# Markdown file in the repo becomes a page — CHANGELOG.md and the
+# _design-system/ mirror included — and every one of them is run through Liquid
+# before Markdown. Two failure modes follow, and neither is loud:
+#
+#   1. An unbalanced `{% raw %}`. Liquid's raw block swallows everything up to
+#      the FIRST `{% endraw %}`, so a stray opener silently eats the rest of the
+#      document. CHANGELOG.md carried one that consumed 945 lines while the
+#      build stayed green.
+#
+#   2. A literal `{% raw %}` / `{% endraw %}` written as documentation prose.
+#      It reads like text but parses as a tag, which is how (1) happens. To show
+#      the tag, escape it: `{% raw %}{% raw %}{% endraw %}`.
+#
+# A Liquid *syntax* error (e.g. `{{…}}`) is caught by the Pages workflow, which
+# fails on "Liquid Warning" in the build output. This script catches the class
+# the build cannot report, because swallowed text is not an error to Liquid.
+#
+# Usage:
+#   scripts/lint-liquid-raw.rb            # scan the rendered Markdown surface
+#   scripts/lint-liquid-raw.rb PATH...    # scan specific files
+#   scripts/lint-liquid-raw.rb --verbose  # list every file scanned
+# ---------------------------------------------------------------------------
+
+ROOT = File.expand_path('..', __dir__)
+TAG = /\{%-?\s*(raw|endraw)\s*-?%\}/.freeze
+
+# The escape form: a raw block whose entire body is one raw/endraw tag, which
+# is how you render the tag as text. Blanked before scanning so the literal it
+# carries is not mistaken for a real tag.
+ESCAPED = /\{%-?\s*raw\s*-?%\}\{%-?\s*(?:raw|endraw)\s*-?%\}\{%-?\s*endraw\s*-?%\}/.freeze
+
+# Directories Jekyll never reads, plus the ones _config.yml excludes. Kept in
+# sync with the `exclude:` list; a path missing here only costs a false
+# positive, never a missed one.
+SKIP_DIRS = %w[
+  .git .github .claude .cursor .devcontainer .frontmatter .vscode .obsidian
+  .jekyll-cache .sass-cache _site node_modules vendor pkg logs
+  docs scripts templates test tests examples submodules gemfiles docker lib
+].freeze
+
+# True when `pos` sits inside a single-backtick code span: an odd number of
+# backtick runs precede it on its own line.
+def in_code_span?(text, pos)
+  bol = text.rindex("\n", pos - 1)
+  line = text[(bol ? bol + 1 : 0)...pos]
+  line.scan(/`+/).size.odd?
+end
+
+def scan(path)
+  # Blank the escape form (keeping byte offsets and newlines) so the literal
+  # tag it renders is not read as a tag itself.
+  text = File.read(path, encoding: 'UTF-8')
+             .gsub(ESCAPED) { |m| ' ' * m.length }
+  problems = []
+  in_raw = false
+  opened_at = nil
+  opened_in_span = false
+
+  text.to_enum(:scan, TAG).each do
+    match = Regexp.last_match
+    line = text[0, match.begin(0)].count("\n") + 1
+    if in_raw
+      # Inside a raw block every tag is literal text — nothing to check.
+      if match[1] == 'endraw'
+        if opened_in_span && line != opened_at
+          problems << "#{path}:#{opened_at}: `{% raw %}` inside a code span " \
+                      "opens a block that only closes at line #{line} — " \
+                      'escape it to show the tag as text'
+        end
+        in_raw = false
+        opened_at = nil
+        opened_in_span = false
+      end
+      next
+    end
+
+    if match[1] == 'raw'
+      in_raw = true
+      opened_at = line
+      # `{% raw %}` inside an inline code span is the documentation-mention
+      # trap: it reads as text but opens a real block. Legitimate inline use
+      # (`{% raw %}{{ x }}{% endraw %}`) closes on the same line; a mention
+      # does not, and swallows everything up to the next `{% endraw %}`.
+      opened_in_span = in_code_span?(text, match.begin(0))
+    else
+      problems << "#{path}:#{line}: `{% endraw %}` with no matching `{% raw %}`"
+    end
+  end
+
+  if in_raw
+    problems << "#{path}:#{opened_at}: `{% raw %}` is never closed — " \
+                'Liquid will swallow the rest of the file'
+  end
+  problems
+rescue ArgumentError, Encoding::InvalidByteSequenceError => e
+  ["#{path}: could not read as UTF-8 (#{e.class})"]
+end
+
+def markdown_files
+  Dir.chdir(ROOT) do
+    Dir.glob('**/*.{md,markdown}', File::FNM_DOTMATCH).reject do |p|
+      p.split(File::SEPARATOR).any? { |seg| SKIP_DIRS.include?(seg) }
+    end.sort
+  end
+end
+
+verbose = ARGV.delete('--verbose')
+targets = ARGV.empty? ? markdown_files : ARGV
+
+problems = []
+Dir.chdir(ROOT) do
+  targets.each do |path|
+    next unless File.file?(path)
+
+    warn "  scanning #{path}" if verbose
+    problems.concat(scan(path))
+  end
+end
+
+if problems.empty?
+  puts "✓ lint-liquid-raw: #{targets.size} Markdown files, all " \
+       '`{% raw %}` blocks balanced'
+  exit 0
+end
+
+warn '✗ lint-liquid-raw: unbalanced Liquid raw blocks'
+problems.each { |p| warn "  #{p}" }
+warn ''
+warn 'To display a literal tag, escape it: `{% raw %}{% raw %}{% endraw %}`'
+exit 1

data/scripts/test/integration/mermaid

@@ -142,15 +142,16 @@ test_mermaid_init() {
     local url="$1"
     local description="$2"
     
-    run_test "$description" "curl -s '$url' | grep -q 'mermaid.initialize'"
+    run_test "$description" "curl -s '$url' | grep -q 'mermaid-diagrams.js'"
 }
 
-# Test diagram rendering
+# Test diagram presence (a ```mermaid fence is served as code.language-mermaid;
+# the deferred script turns it into a figure in the browser)
 test_diagram_rendering() {
     local url="$1"
     local description="$2"
-    
-    run_test "$description" "curl -s '$url' | grep -q 'class=\"mermaid\"'"
+
+    run_test "$description" "curl -s '$url' | grep -q 'language-mermaid'"
 }
 
 # Main test execution
@@ -179,16 +180,29 @@ main() {
     # Mermaid include file tests
     log_info "Testing Mermaid include file..."
     
-    test_file_content "_includes/components/mermaid.html" "site.mermaid.src" "Mermaid script from _config (local vendor path)"
-    test_file_content "_includes/components/mermaid.html" "mermaid.initialize" "Mermaid initialization script"
-    test_file_content "_includes/components/mermaid.html" "data-bs-theme" "Bootstrap theme detection configured"
-    test_file_content "_includes/components/mermaid.html" "getMermaidConfig" "Adaptive light/dark theming configured"
+    test_file_content "_includes/components/mermaid.html" "mm.src" "Mermaid script from _config (local vendor path)"
+    test_file_content "_includes/components/mermaid.html" "mermaidConfig" "Diagram config block emitted for the behaviour script"
+    test_file_content "_includes/components/mermaid.html" "mermaid-diagrams.js" "Behaviour script loaded after the vendor bundle"
+    test_file_content "_includes/components/mermaid.html" "defer" "Scripts are deferred (never block parsing)"
+
+    # Behaviour script (assets/js/mermaid-diagrams.js)
+    log_info "Testing diagram behaviour script..."
+
+    test_file_exists "assets/js/mermaid-diagrams.js" "Diagram behaviour script exists"
+    test_file_content "assets/js/mermaid-diagrams.js" "mermaid.initialize" "Mermaid initialization"
+    test_file_content "assets/js/mermaid-diagrams.js" "data-bs-theme" "Colour-mode change observed for re-render"
+    test_file_content "assets/js/mermaid-diagrams.js" "data-theme-skin" "Skin change observed for re-render"
+    test_file_content "assets/js/mermaid-diagrams.js" "themeVariables" "Palette derived into Mermaid theme variables"
+    test_file_content "assets/js/mermaid-diagrams.js" "zer0Mermaid" "Public API exposed"
+    test_file_exists "_sass/components/_mermaid.scss" "Diagram figure styles exist"
+    test_file_content "assets/css/main.scss" "components/mermaid" "Diagram styles imported by the stylesheet manifest"
     
     # Documentation tests
     log_info "Testing documentation..."
     
     test_file_content "pages/_docs/features/mermaid-diagrams.md" "mermaid: true" "Main docs have front matter"
     test_file_content "pages/_docs/features/mermaid-diagrams.md" "graph TD" "Main docs have examples"
+    test_file_content "pages/_docs/features/mermaid-diagrams.md" "accTitle" "Main docs cover accessible captions"
     
     # Server tests (if not quick mode)
     if [ "$QUICK" = false ]; then

data/scripts/test/lib/run_tests.sh

@@ -131,7 +131,9 @@ main() {
     source "$TEST_DIR/test_migrate.sh"
     source "$TEST_DIR/test_pixelate_images.sh"
     source "$TEST_DIR/test_content_review.sh"
-    
+    source "$TEST_DIR/test_agent_review_result.sh"
+    source "$TEST_DIR/test_visual_evidence_autogen.sh"
+
     # Summary
     echo -e "\n${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
     echo -e "${BLUE}Test Summary${NC}"

data/scripts/test/lib/test_agent_review_result.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# Bridge for scripts/ci/test_agent_review_result.py (issue #418).
+#
+# The guard that decides whether the Claude content review actually ran lives in
+# scripts/ci/agent_review_result.py, next to the other CI helper
+# (classify_changes.py), and its tests are written in Python beside it. This
+# wrapper is what puts them on the CI path: run_tests.sh sources this file, and
+# ./scripts/bin/test runs run_tests.sh on every PR.
+#
+# scripts/issues/test_verify_close.py is the cautionary example — a real test
+# suite that no runner ever invoked. Do not let this one drift the same way: if
+# the Python tests move, move this line with them.
+
+ARR_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+
+print_suite_header "Claude review guard (scripts/ci/agent_review_result.py)"
+
+if command -v python3 >/dev/null 2>&1; then
+    arr_output="$(python3 "$ARR_ROOT/scripts/ci/test_agent_review_result.py" 2>&1)"
+    arr_status=$?
+    echo "$arr_output"
+    assert_equals "0" "$arr_status" \
+        "scripts/ci/test_agent_review_result.py passes (the #418 401-swallow guard)"
+else
+    echo "python3 not available — skipping the Claude review guard tests"
+fi

data/scripts/test/lib/test_visual_evidence_autogen.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# Bridge for scripts/ci/test_visual_evidence_autogen.py (ZER0-085).
+#
+# The planner/decider behind visual-evidence-autogen.yml lives in
+# scripts/ci/visual_evidence_autogen.py, next to the other CI helpers, and its
+# tests are Python beside it. This wrapper puts them on the CI path: run_tests.sh
+# sources this file, and ./scripts/bin/test runs run_tests.sh on every PR — the
+# same arrangement as test_agent_review_result.sh, for the same reason (a test
+# suite no runner invokes rots silently).
+
+VEA_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+
+print_suite_header "Visual-evidence autogen planner (scripts/ci/visual_evidence_autogen.py)"
+
+if command -v python3 >/dev/null 2>&1; then
+    vea_output="$(python3 "$VEA_ROOT/scripts/ci/test_visual_evidence_autogen.py" 2>&1)"
+    vea_status=$?
+    echo "$vea_output"
+    assert_equals "0" "$vea_status" \
+        "scripts/ci/test_visual_evidence_autogen.py passes (plan/decide/contract guards)"
+else
+    echo "python3 not available — skipping the visual-evidence autogen tests"
+fi