jekyll-theme-zer0 1.17.1 → 1.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50907837fd27d28fa1bea1cf163d7e2d71a4a848266c861656b8d8ebdb2e3d78
-  data.tar.gz: e3853573f9cca38ec51ce145a8279aedf221035afac88cf9cfc77d220dee23e5
+  metadata.gz: 75211dc29d6baba87f5cc1264e9b3f47ecbff99d02cbe875f9b2290472c3bd09
+  data.tar.gz: 3fb6eb26ee2507c079ebc1f1c91db92687706a14607cba9685b95ff20ad0ffa8
 SHA512:
-  metadata.gz: b1dcd28c12fd2c48e14463bf4e7db63ed3c024262ca3bc04ba98a9ce8b3b53affef695846681fee898584184a58790a86361e00940d89a0ecbe76e0dddb54496
-  data.tar.gz: e28d9a6a97edefc45d7b772e363a1826b3a96e00de15e58e90be84cae1c7fa2ad23a24198769ea4f13cdbeac138cbf4f02fd75356d8066e8cb5c69ae9b40558a
+  metadata.gz: f7b6b73449bbc1efbea5243b4fc65e3b470b7c260c6e853f1729559d2a8402d0f3070e684cf3d9277d1ccee2b077022c32142c9de8a2b922825415d2cde46534
+  data.tar.gz: 012f8d69f7c6305f7d9901292ba57ae2d0884f9ffb162e10836efb739cf17546b709de109d86b05fdfa6929f89c1e84398f6e4a61bb6c7552a7e574de7f9d627

data/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.18.1] - 2026-06-14
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- ae76a61f fix(content-review): correct code-fence detection (closing fences + {% raw %}) (#155)
+- f00fb654 docs(seo): strengthen SEO docs index metadata + fix agent-tier workflow (#154)
+
+### Fixed
+- **content-review: closing code fences no longer counted as "missing language"**.
+  `scripts/content-review.rb` flagged every bare ```` ``` ```` line, including the
+  *closing* fence of a properly tagged block, which double-counted and could tank
+  a file's score (e.g. `pages/_about/features/jekyll.md` scored 0/100 almost
+  entirely from this false positive). The check now tracks fence open/close state
+  and only validates opening fences.
+- **content-review: ignore Liquid `{% raw %}` blocks** in the quality and style
+  checks. Code fences, headings, images, and terminology inside `{% raw %}…
+  {% endraw %}` are literal display examples, not page structure, and were being
+  counted as real findings.
+
+## [1.18.0] - 2026-06-13
+
+### Changed
+- Version bump: minor release
+
+### Commits in this release
+- e7c8e33c feat(content-review): AI content reviewer framework with Claude Code agent (#153)
+- c78433f1 fix(content): render mermaid on 12 pages, restore Obsidian graph, migration tests (T-019) (#150)
+
+### Added
+- **AI content reviewer framework**: a two-tier reviewer that runs on every PR
+  touching `pages/**/*.md` and integrates with Claude Code agents to ensure SEO
+  is met and content is consistent, polished, and styled to the collection's
+  guidelines.
+  - **Deterministic tier** — `scripts/content-review.rb` (Ruby, stdlib-only, no
+    API key, works on fork PRs) scores each file 0–100 for front matter, SEO
+    (title/description length, keywords), structure (headings, code-fence
+    languages, image alt text, bare URLs), and terminology. Thresholds are
+    derived **per collection** (posts as articles, docs under the documentation
+    guidelines, notes/notebooks as short-form, etc.).
+  - **Claude Code agent tier** — `.claude/agents/content-reviewer.md` reviews
+    tone, clarity, consistency, accessibility, and technical accuracy, loading
+    each file's governing instruction files (baseline + collection-specific).
+  - **Automation** — `.github/workflows/ai-content-review.yml` posts the
+    deterministic summary as a sticky PR comment (always) and runs the Claude
+    Code agent when `ANTHROPIC_API_KEY` is configured.
+  - **Config & guidance** — `.github/config/content_review.yml` (per-collection
+    thresholds + assigned skills/prompts), `.github/instructions/content-review.instructions.md`,
+    the `/content-review` prompt + Cursor command, and the `content-review` skill.
+
 ## [1.17.1] - 2026-06-13
 
 ### Changed
@@ -14,6 +65,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - f2657b68 fix(a11y): resolve all navbar & site WCAG 2.1 AA violations (T-007) (#149)
 - 30d836cb fix(admin): sync config-page copy with live _config.yml and redact the Raw tab (T-018) (#148)
 
+### Added
+- **Mermaid diagrams now render on 12 more pages**: pages with ```mermaid``` code fences but no `mermaid: true` front-matter flag (about, several feature/dev docs, all four quickstart guides) were showing raw code instead of diagrams — the flag gates the renderer include. Added the flag; verified all 34 diagrams across the site parse with valid Mermaid syntax and render to SVG in a browser
+- **Obsidian graph view restored**: the `/docs/obsidian/graph/` page (roadmap v1.4 force-directed knowledge graph) had been deleted as a "stub" but its `full-graph.html` include, `obsidian-graph.js`, the docs index link, and 5 inbound wiki-links all still referenced it — a 404 to a shipped feature. Restored the page (it renders 161 nodes / 269 edges from the live wiki-index with zero console errors)
+- **Migration & theme-version coverage (T-019)**: `scripts/test/lib/test_migrate.sh` (14 assertions for Jekyll-site detection, theme-connection classification, and version-gap logic) and `ThemeVersionGeneratorTest` in `test/test_plugins.rb` — the two largest remaining zero-coverage subsystems from the T-005 baseline
+
 ### Fixed
 - **Navbar & site accessibility (T-007)**: resolved all WCAG 2.1 AA violations that kept three axe-core audits frozen — dropped the redundant ARIA `menubar`/`menuitem` roles from the nav (the nav landmark already provides semantics; menubars require menuitem children the search/settings buttons weren't), added an `aria-label` to the site-subtitle home link, kept the admin/footer separator a list item, gave the theme-preview disabled tab a `role="tab"` and an icon-only button an `aria-label`, made code blocks a single keyboard-focusable scroll region, and underlined prose links so they're distinguishable without color. The three `test.fixme` blocks in `test/visual/accessibility.spec.js` are now live `test()` calls — verified 0 violations across the homepage, FAQ, and all 8 admin pages (23/23 a11y, 223/223 smoke tier)
 

data/README.md

@@ -2,7 +2,7 @@
 title: zer0-mistakes
 sub-title: AI-Native Jekyll Theme
 description: AI-native Jekyll theme for GitHub Pages — Docker-first development, AI-powered installation, multi-agent integration (Copilot, Codex, Cursor, Claude), AI preview-image generation, and AIEO content optimization with Bootstrap 5.3.
-version: 1.17.1
+version: 1.18.1
 layout: landing
 tags:
   - jekyll
@@ -20,7 +20,7 @@ categories:
   - bootstrap
   - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-06-13T04:17:52.000Z
+lastmod: 2026-06-14T14:41:09.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -911,7 +911,7 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 1.17.1 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 1.18.1 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
 | **Documented Features** | 43 ([Feature Registry](https://github.com/bamr87/zer0-mistakes/blob/main/_data/features.yml)) |
 | **Setup Time** | 2-5 minutes ([install.sh benchmarks](https://github.com/bamr87/zer0-mistakes/blob/main/install.sh)) |
 | **Documentation Pages** | 70+ ([browse docs](https://zer0-mistakes.com/pages/)) |
@@ -966,6 +966,6 @@ And these AI partners that make zer0-mistakes truly AI-native:
 
 **Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
 
-**v1.17.1** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
+**v1.18.1** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
 
 

data/_data/backlog.yml

@@ -56,7 +56,7 @@
 meta:
   title: "zer0-mistakes Backlog"
   updated: 2026-06-12
-  next_id: 21
+  next_id: 22
 
 tasks:
   # --- Housekeeping (seeded so the loop has work on day one) ------------------
@@ -504,7 +504,7 @@ tasks:
 
   - id: T-019
     title: "Unit tests for migrate.sh and theme_version.rb (coverage rank #1)"
-    status: open
+    status: done
     priority: P2
     area: tests
     risk: standard
@@ -516,13 +516,18 @@ tasks:
       detection, theme connection, admin-page install/verify, version-gap
       detection) plus _plugins/theme_version.rb (88 lines) as the largest
       remaining zero-coverage surface (353 lines).
+      Done 2026-06-13: scripts/test/lib/test_migrate.sh (14 assertions:
+      detect_jekyll_site, validate_theme_connection classification for
+      remote/gem/local, detect_version_gap min-version logic) and
+      ThemeVersionGeneratorTest in test_plugins.rb (remote/unknown-gem/none
+      branches, gem scan stubbed for determinism).
     acceptance:
       - "scripts/test/lib/test_migrate.sh exercises detect_jekyll_site, validate_theme_connection, and detect_version_gap against fixture directories."
       - "test/test_plugins.rb (or a sibling spec) covers theme_version.rb's version resolution."
       - "./scripts/bin/test stays green with the new specs included."
     links: { issue: null, pr: null, roadmap: "1.14" }
     created: 2026-06-12
-    updated: 2026-06-12
+    updated: 2026-06-13
 
   - id: T-020
     title: "CI coverage for installer interactive wizard and upgrade path (coverage rank #2)"
@@ -545,3 +550,26 @@ tasks:
     links: { issue: null, pr: null, roadmap: "1.14" }
     created: 2026-06-12
     updated: 2026-06-12
+
+  - id: T-021
+    title: "Vendor cytoscape.js so the Obsidian graph works without a CDN"
+    status: open
+    priority: P3
+    area: feat
+    risk: standard
+    effort: S
+    source: audit
+    summary: >-
+      The Obsidian full-graph page (_includes/obsidian/full-graph.html) loads
+      cytoscape.js from cdn.jsdelivr.net — the only runtime CDN dependency left
+      in the theme, contradicting the vendored-assets principle (Bootstrap,
+      Icons, Mermaid are all under assets/vendor/). It also makes the graph
+      fail under strict CSP or offline. Vendor cytoscape@3.30.0 under
+      assets/vendor/ and reference it locally, matching the Mermaid pattern.
+    acceptance:
+      - "cytoscape.min.js committed under assets/vendor/ and referenced via a local path."
+      - "full-graph.html no longer references cdn.jsdelivr.net."
+      - "The graph page renders nodes/edges with the vendored file (no network)."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-06-13
+    updated: 2026-06-13

data/scripts/content-review.rb

@@ -0,0 +1,470 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# content-review.rb
+# =============================================================================
+#
+# Deterministic (no-API) tier of the AI content reviewer framework.
+#
+# Scores Jekyll content files for SEO and content quality using the thresholds
+# in .github/config/content_review.yml and the required-field schema in
+# .github/config/frontmatter_schema.yml. Designed to run anywhere — locally,
+# in CI, and on fork PRs without secrets — so contributors get fast, mechanical
+# feedback before (and independently of) the Claude Code agent tier.
+#
+# Usage:
+#   ruby scripts/content-review.rb --changed --base origin/main   # diff vs base
+#   ruby scripts/content-review.rb --files "a.md b.md"            # explicit files
+#   ruby scripts/content-review.rb --files a.md --json out.json --summary out.md
+#   ruby scripts/content-review.rb --changed --strict            # non-zero on fail
+#
+# Options:
+#   --files LIST      Space/newline-separated markdown files to review
+#   --changed         Review files changed vs --base (git diff)
+#   --base REF        Base git ref for --changed (default: origin/main)
+#   --config PATH     content_review.yml (default: .github/config/content_review.yml)
+#   --schema PATH     frontmatter_schema.yml (default: .github/config/frontmatter_schema.yml)
+#   --json PATH       Write machine-readable JSON results
+#   --summary PATH    Write a Markdown summary (suitable for a PR comment)
+#   --strict          Exit non-zero if any file scores below the fail threshold
+#   --quiet           Suppress the human-readable stdout table
+#   --help            Show this help
+#
+# Exit codes:
+#   0  clean (or warn mode)
+#   1  one or more files below fail threshold (only when --strict)
+#   2  invalid arguments / no files
+#   3  config or parse error
+#
+# No gem dependencies beyond the Ruby stdlib.
+# =============================================================================
+
+require 'yaml'
+require 'json'
+require 'optparse'
+require 'date'
+
+# Content is UTF-8; force it so checks don't trip on emoji/accents under a
+# US-ASCII locale (common on minimal CI runners).
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+ROOT = File.expand_path('..', __dir__)
+
+# --- Severity helpers --------------------------------------------------------
+SEVERITIES = %w[error warning info].freeze
+
+Issue = Struct.new(:severity, :category, :message)
+
+# --- Options -----------------------------------------------------------------
+options = {
+  files: nil,
+  changed: false,
+  base: ENV['CONTENT_REVIEW_BASE'] || 'origin/main',
+  config: File.join(ROOT, '.github', 'config', 'content_review.yml'),
+  schema: File.join(ROOT, '.github', 'config', 'frontmatter_schema.yml'),
+  json: nil,
+  summary: nil,
+  strict: false,
+  quiet: false
+}
+
+parser = OptionParser.new do |o|
+  o.banner = 'Usage: ruby scripts/content-review.rb [options]'
+  o.on('--files LIST', 'Files to review (space/newline separated)') { |v| options[:files] = v }
+  o.on('--changed', 'Review files changed vs --base') { options[:changed] = true }
+  o.on('--base REF', 'Base git ref for --changed') { |v| options[:base] = v }
+  o.on('--config PATH', 'content_review.yml path') { |v| options[:config] = v }
+  o.on('--schema PATH', 'frontmatter_schema.yml path') { |v| options[:schema] = v }
+  o.on('--json PATH', 'Write JSON results') { |v| options[:json] = v }
+  o.on('--summary PATH', 'Write Markdown summary') { |v| options[:summary] = v }
+  o.on('--strict', 'Exit non-zero on failing files') { options[:strict] = true }
+  o.on('--quiet', 'Suppress stdout table') { options[:quiet] = true }
+  o.on('-h', '--help', 'Show help') { puts o; exit 0 }
+end
+
+begin
+  parser.parse!(ARGV)
+rescue OptionParser::ParseError => e
+  warn "Error: #{e.message}"
+  warn parser
+  exit 2
+end
+
+# --- Load configuration ------------------------------------------------------
+def load_yaml(path)
+  YAML.safe_load(File.read(path), permitted_classes: [Date, Time], aliases: true) || {}
+rescue StandardError => e
+  warn "Failed to read #{path}: #{e.message}"
+  exit 3
+end
+
+unless File.exist?(options[:config])
+  warn "Config not found: #{options[:config]}"
+  exit 3
+end
+
+CONFIG = load_yaml(options[:config])
+SCHEMA = File.exist?(options[:schema]) ? load_yaml(options[:schema]) : {}
+
+# Backward-compatible: v2 uses `defaults:`, but fall back to top-level keys.
+DEFAULTS = CONFIG['defaults'] || CONFIG
+COLLECTION_CFG = CONFIG['collections'] || {}
+DEFAULT_FAIL_UNDER = ((DEFAULTS['scoring'] || {})['fail_under'] || 70).to_i
+
+# Recursively merge `override` onto `base` (override wins; hashes merge deep).
+def deep_merge(base, override)
+  return base if override.nil?
+  return override unless base.is_a?(Hash) && override.is_a?(Hash)
+
+  merged = base.dup
+  override.each do |k, v|
+    merged[k] = merged.key?(k) ? deep_merge(merged[k], v) : v
+  end
+  merged
+end
+
+# Effective rules for a collection = deep-merge(defaults, collections[name]).
+# `collections.*` in frontmatter_schema.yml may differ from content_review.yml;
+# here we only merge the review config, not the schema.
+def effective_config(collection)
+  base = DEFAULTS
+  override = collection ? (COLLECTION_CFG[collection] || {}) : {}
+  deep_merge(base, override)
+end
+
+# --- Resolve the list of files ----------------------------------------------
+def git_changed_files(base)
+  merge_base = `git merge-base #{base} HEAD 2>/dev/null`.strip
+  ref = merge_base.empty? ? base : merge_base
+  out = `git diff --name-only --diff-filter=ACMR #{ref} HEAD 2>/dev/null`
+  out.split("\n").map(&:strip).reject(&:empty?)
+end
+
+def excluded?(path, config)
+  patterns = (config['scope'] || {})['exclude'] || []
+  patterns.any? { |g| File.fnmatch(g, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+end
+
+def included?(path, config)
+  patterns = (config['scope'] || {})['include'] || []
+  patterns.any? { |g| File.fnmatch(g, path, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+end
+
+raw_files =
+  if options[:files]
+    options[:files].split(/[\s\n]+/).map(&:strip).reject(&:empty?)
+  elsif options[:changed]
+    git_changed_files(options[:base])
+  else
+    warn 'Nothing to review: pass --files or --changed.'
+    exit 2
+  end
+
+files = raw_files
+        .select { |f| f.end_with?('.md') }
+        .select { |f| included?(f, CONFIG) && !excluded?(f, CONFIG) }
+        .select { |f| File.exist?(File.join(ROOT, f)) || File.exist?(f) }
+        .uniq
+
+if files.empty?
+  puts 'No in-scope content files to review.'
+  # Still emit empty artifacts so downstream steps don't choke.
+  File.write(options[:json], JSON.pretty_generate({ 'files' => [], 'average_score' => nil })) if options[:json]
+  File.write(options[:summary], "## 📝 Content Review\n\nNo in-scope content files changed.\n") if options[:summary]
+  exit 0
+end
+
+# --- Front matter + body parsing --------------------------------------------
+def split_front_matter(text)
+  if text =~ /\A---\s*\n(.*?)\n---\s*\n?(.*)\z/m
+    [Regexp.last_match(1), Regexp.last_match(2)]
+  else
+    [nil, text]
+  end
+end
+
+def parse_front_matter(yaml_text)
+  return {} if yaml_text.nil? || yaml_text.strip.empty?
+
+  YAML.safe_load(yaml_text, permitted_classes: [Date, Time], aliases: true) || {}
+rescue StandardError
+  nil # signals a parse error
+end
+
+# Remove fenced code blocks so prose checks don't trip on code.
+def strip_code_fences(body)
+  body.gsub(/^```.*?^```/m, '').gsub(/`[^`]*`/, '')
+end
+
+# Remove Liquid {% raw %}...{% endraw %} regions. Content inside them is a
+# literal display example (often showing ``` fences or {{ }} tags), not real
+# page structure, so it must not be counted by the quality/style checks.
+def strip_liquid_raw(body)
+  body.gsub(/\{%-?\s*raw\s*-?%\}.*?\{%-?\s*endraw\s*-?%\}/m, '')
+end
+
+# --- Collection detection ----------------------------------------------------
+def detect_collection(path, schema)
+  collections = schema['collections'] || {}
+  # Match specific collections before the generic top-level `pages` pattern.
+  ordered = collections.sort_by { |name, _| name == 'pages' ? 1 : 0 }
+  ordered.each do |name, spec|
+    pattern = spec['path_pattern']
+    next unless pattern
+
+    return name if File.fnmatch(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+  end
+  nil
+end
+
+# --- Individual checks -------------------------------------------------------
+def check_frontmatter(fm, collection, schema)
+  issues = []
+  return [Issue.new('error', 'frontmatter', 'No front matter block found')] if fm.nil?
+  return [Issue.new('error', 'frontmatter', 'Front matter is not valid YAML')] if fm == :parse_error
+
+  spec = (schema['collections'] || {})[collection]
+  required = spec ? (spec['required'] || []) : []
+  required.each do |field|
+    val = fm[field]
+    if val.nil? || (val.respond_to?(:empty?) && val.empty?)
+      issues << Issue.new('error', 'frontmatter', "Missing required field: `#{field}`")
+    end
+  end
+
+  # categories/tags should be lists, not bare strings.
+  %w[categories tags].each do |field|
+    next unless fm.key?(field)
+
+    issues << Issue.new('warning', 'frontmatter', "`#{field}` should be a YAML list, not a bare string") if fm[field].is_a?(String)
+  end
+  issues
+end
+
+def check_seo(fm, seo)
+  issues = []
+  return issues if fm.nil? || fm == :parse_error
+
+  title = fm['title'].to_s
+  unless title.empty?
+    t = (seo['title'] || {})
+    min = (t['min_length'] || 30).to_i
+    max = (t['max_length'] || 60).to_i
+    if title.length < min
+      issues << Issue.new('warning', 'seo', "Title is #{title.length} chars (aim for #{min}–#{max})")
+    elsif title.length > max
+      issues << Issue.new('warning', 'seo', "Title is #{title.length} chars — over #{max}, will truncate in search results")
+    end
+  end
+
+  desc = fm['description'].to_s
+  d = (seo['description'] || {})
+  dmin = (d['min_length'] || 120).to_i
+  dmax = (d['max_length'] || 160).to_i
+  if desc.empty?
+    issues << Issue.new('warning', 'seo', 'No meta description — add a 120–160 char `description`')
+  elsif desc.length < dmin
+    issues << Issue.new('warning', 'seo', "Description is #{desc.length} chars (aim for #{dmin}–#{dmax})")
+  elsif desc.length > dmax
+    issues << Issue.new('warning', 'seo', "Description is #{desc.length} chars — over #{dmax}, will truncate")
+  end
+
+  kw = (seo['keywords'] || {})
+  if kw['recommended']
+    keywords = fm['keywords']
+    if keywords.nil?
+      issues << Issue.new('info', 'seo', 'No `keywords` — a 3–10 item list aids AI-engine optimization (AIEO)')
+    elsif keywords.is_a?(Array)
+      kmin = (kw['min'] || 3).to_i
+      kmax = (kw['max'] || 10).to_i
+      issues << Issue.new('info', 'seo', "Only #{keywords.length} keyword(s) — aim for #{kmin}–#{kmax}") if keywords.length < kmin
+      issues << Issue.new('info', 'seo', "#{keywords.length} keywords — trim to #{kmax} most relevant") if keywords.length > kmax
+    end
+  end
+
+  if seo['require_preview_image']
+    has_image = %w[preview image og_image].any? { |k| !fm[k].to_s.empty? }
+    issues << Issue.new('info', 'seo', 'No preview/social image set') unless has_image
+  end
+  issues
+end
+
+def check_quality(body, quality)
+  issues = []
+  # Liquid {% raw %} examples are display-only — exclude them from every check.
+  body = strip_liquid_raw(body)
+  prose = strip_code_fences(body)
+  words = prose.split(/\s+/).reject(&:empty?)
+  wc = words.length
+
+  min_wc = (quality['min_word_count'] || 100).to_i
+  max_wc = (quality['max_word_count'] || 3500).to_i
+  if wc < min_wc
+    issues << Issue.new('warning', 'quality', "Only ~#{wc} words — below the #{min_wc}-word minimum (reads as a stub)")
+  elsif wc > max_wc
+    issues << Issue.new('info', 'quality', "~#{wc} words — over #{max_wc}; consider splitting into multiple pages")
+  end
+
+  # Heading structure (ignore headings inside code fences).
+  headings = body.gsub(/^```.*?^```/m, '').scan(/^(#{'#'}{1,6})\s+\S/).map { |m| m[0].length }
+  h2_plus = headings.count { |lvl| lvl >= 2 }
+  min_h2 = (quality['min_h2_headings'] || 1).to_i
+  issues << Issue.new('info', 'quality', "Fewer than #{min_h2} H2 heading(s) — add sections for scannability") if h2_plus < min_h2
+
+  max_skip = (quality['max_heading_skip'] || 1).to_i
+  headings.each_cons(2) do |a, b|
+    if b - a > max_skip
+      issues << Issue.new('warning', 'quality', "Heading level jumps from H#{a} to H#{b} — don't skip levels")
+      break
+    end
+  end
+
+  # Code fences must declare a language.
+  if quality['require_code_fence_language']
+    # Only opening fences need a language; toggle state so the matching closing
+    # fence (a bare ```) is not counted.
+    in_fence = false
+    body.each_line do |line|
+      next unless line =~ /^\s*```(.*)$/
+
+      if in_fence
+        in_fence = false # closing fence — no language required
+      else
+        in_fence = true
+        issues << Issue.new('info', 'quality', 'Code fence without a language (use ```bash, ```ruby, …)') if Regexp.last_match(1).strip.empty?
+      end
+    end
+  end
+
+  # Images must have alt text.
+  if quality['require_image_alt_text']
+    body.scan(/!\[(.*?)\]\(([^)]*)\)/).each do |alt, src|
+      issues << Issue.new('warning', 'accessibility', "Image missing alt text: `#{src}`") if alt.strip.empty?
+    end
+  end
+
+  # Bare URLs.
+  if quality['flag_bare_urls']
+    bare = strip_code_fences(body).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
+end
+
+def check_style(body, style)
+  issues = []
+  prose = strip_code_fences(strip_liquid_raw(body))
+  (style['terminology'] || {}).each do |wrong, right|
+    next if wrong.to_s.empty?
+
+    if prose.match?(/\b#{Regexp.escape(wrong)}\b/)
+      issues << Issue.new('info', 'style', "Use \"#{right}\" instead of \"#{wrong}\"")
+    end
+  end
+  issues
+end
+
+# --- Scoring -----------------------------------------------------------------
+def score_for(issues, weights)
+  penalty = issues.sum { |i| (weights[i.severity] || 0).to_i }
+  [100 - penalty, 0].max
+end
+
+def verdict(score, scoring)
+  th = scoring['thresholds'] || {}
+  return '🟢 excellent' if score >= (th['excellent'] || 90).to_i
+  return '🟡 acceptable' if score >= (th['acceptable'] || 70).to_i
+
+  '🔴 needs work'
+end
+
+# --- Run ---------------------------------------------------------------------
+results = []
+
+files.each do |rel|
+  abs = File.exist?(rel) ? rel : File.join(ROOT, rel)
+  text = File.read(abs, encoding: 'UTF-8')
+  fm_text, body = split_front_matter(text)
+  fm = parse_front_matter(fm_text)
+  fm = :parse_error if fm.nil? && !fm_text.nil?
+
+  collection = detect_collection(rel, SCHEMA)
+  eff = effective_config(collection)
+  weights = (eff['scoring'] || {})['weights'] || { 'error' => 15, 'warning' => 5, 'info' => 1 }
+  fail_under = ((eff['scoring'] || {})['fail_under'] || DEFAULT_FAIL_UNDER).to_i
+
+  issues = []
+  issues.concat(check_frontmatter(fm == :parse_error ? :parse_error : fm, collection, SCHEMA))
+  issues.concat(check_seo(fm, eff['seo'] || {}))
+  issues.concat(check_quality(body, eff['quality'] || {}))
+  issues.concat(check_style(body, eff['style'] || {}))
+
+  score = score_for(issues, weights)
+  results << {
+    'file' => rel,
+    'collection' => collection,
+    'score' => score,
+    'fail_under' => fail_under,
+    'verdict' => verdict(score, eff['scoring'] || {}),
+    'instructions' => eff['instructions'] || [],
+    'issues' => issues.map { |i| { 'severity' => i.severity, 'category' => i.category, 'message' => i.message } }
+  }
+end
+
+avg = results.empty? ? nil : (results.sum { |r| r['score'] } / results.length.to_f).round(1)
+failing = results.select { |r| r['score'] < r['fail_under'] }
+
+# --- Markdown summary --------------------------------------------------------
+def render_summary(results, avg, fail_under)
+  lines = []
+  lines << '## 📝 AI Content Review — deterministic checks'
+  lines << ''
+  lines << "Reviewed **#{results.length}** file(s) · average score **#{avg}/100** · pass threshold **#{fail_under}** (per-collection)."
+  lines << ''
+  lines << '| File | Collection | Score | Verdict |'
+  lines << '| --- | --- | ---: | --- |'
+  results.sort_by { |r| r['score'] }.each do |r|
+    lines << "| `#{r['file']}` | #{r['collection'] || '—'} | #{r['score']}/#{r['fail_under']} | #{r['verdict']} |"
+  end
+  lines << ''
+
+  emoji = { 'error' => '❌', 'warning' => '⚠️', 'info' => 'ℹ️' }
+  results.each do |r|
+    next if r['issues'].empty?
+
+    lines << "<details><summary><code>#{r['file']}</code> — #{r['issues'].length} item(s), score #{r['score']}</summary>"
+    lines << ''
+    r['issues'].sort_by { |i| SEVERITIES.index(i['severity']) || 9 }.each do |i|
+      lines << "- #{emoji[i['severity']] || '•'} **#{i['category']}** — #{i['message']}"
+    end
+    lines << ''
+    lines << '</details>'
+    lines << ''
+  end
+
+  lines << '---'
+  lines << '_Deterministic tier (frontmatter + SEO + structure). The Claude Code'
+  lines << 'content-reviewer agent covers tone, clarity, and accuracy separately._'
+  lines.join("\n") + "\n"
+end
+
+summary_md = render_summary(results, avg, DEFAULT_FAIL_UNDER)
+
+# --- Outputs -----------------------------------------------------------------
+File.write(options[:json], JSON.pretty_generate({ 'files' => results, 'average_score' => avg, 'default_fail_under' => DEFAULT_FAIL_UNDER })) if options[:json]
+File.write(options[:summary], summary_md) if options[:summary]
+
+unless options[:quiet]
+  results.sort_by { |r| r['score'] }.each do |r|
+    puts "#{r['verdict'].ljust(14)} #{r['score'].to_s.rjust(3)}  #{r['file']}"
+    r['issues'].each { |i| puts "    [#{i['severity']}] #{i['category']}: #{i['message']}" }
+  end
+  puts ''
+  puts "Average: #{avg}/100  (#{results.length} file(s), default threshold #{DEFAULT_FAIL_UNDER})"
+  puts "Failing: #{failing.map { |r| r['file'] }.join(', ')}" unless failing.empty?
+end
+
+exit 1 if options[:strict] && !failing.empty?
+exit 0

data/scripts/test/lib/run_tests.sh

@@ -128,6 +128,7 @@ main() {
     source "$TEST_DIR/test_gem.sh"
     source "$TEST_DIR/test_analyze_commits.sh"
     source "$TEST_DIR/test_locale_independence.sh"
+    source "$TEST_DIR/test_migrate.sh"
     
     # Summary
     echo -e "\n${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

data/scripts/test/lib/test_migrate.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+
+# Unit tests for migrate.sh library (T-019)
+#
+# Drives the pure-logic migration helpers against throwaway fixture
+# directories: site detection, theme-connection classification, and
+# version-gap detection. The template-rendering functions
+# (install_admin_pages / verify_admin_pages) need the full template
+# pipeline and are exercised by the installer e2e suites; these unit
+# tests focus on the detection logic that has had zero coverage.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$(cd "$SCRIPT_DIR/../../lib" && pwd)"
+
+export DRY_RUN=true
+export INTERACTIVE=false
+export VERBOSE=false
+
+source "$LIB_DIR/common.sh"
+source "$LIB_DIR/migrate.sh"
+
+set +e
+
+print_suite_header "migrate.sh"
+
+_mktmp() { mktemp -d "${TMPDIR:-/tmp}/migrate-test-XXXXXX"; }
+
+# --- detect_jekyll_site ---------------------------------------------------
+echo "Testing detect_jekyll_site..."
+
+d=$(_mktmp)
+assert_false "detect_jekyll_site '$d'" "No _config.yml → not a Jekyll site"
+
+touch "$d/_config.yml"
+assert_false "detect_jekyll_site '$d'" "_config.yml alone is not enough"
+
+touch "$d/Gemfile"
+assert_true "detect_jekyll_site '$d'" "_config.yml + Gemfile → Jekyll site"
+rm -rf "$d"
+
+d=$(_mktmp); touch "$d/_config.yml"; mkdir -p "$d/_layouts"
+assert_true "detect_jekyll_site '$d'" "_config.yml + _layouts/ → Jekyll site"
+rm -rf "$d"
+
+# --- validate_theme_connection -------------------------------------------
+echo "Testing validate_theme_connection..."
+
+d=$(_mktmp)
+printf 'remote_theme: "bamr87/zer0-mistakes"\n' > "$d/_config.yml"
+assert_true "validate_theme_connection '$d'" "remote_theme detected"
+validate_theme_connection "$d" >/dev/null 2>&1
+assert_equals "remote" "$THEME_CONNECTION_TYPE" "remote connection type set"
+rm -rf "$d"
+
+d=$(_mktmp)
+printf 'theme: jekyll-theme-zer0\n' > "$d/_config.yml"
+assert_true "validate_theme_connection '$d'" "gem theme detected"
+validate_theme_connection "$d" >/dev/null 2>&1
+assert_equals "gem" "$THEME_CONNECTION_TYPE" "gem connection type set"
+rm -rf "$d"
+
+d=$(_mktmp)
+printf 'title: My Site\n' > "$d/_config.yml"
+printf 'gem "jekyll-theme-zer0", path: "../theme"\n' > "$d/Gemfile"
+assert_true "validate_theme_connection '$d'" "local path gem detected"
+validate_theme_connection "$d" >/dev/null 2>&1
+assert_equals "local" "$THEME_CONNECTION_TYPE" "local connection type set"
+rm -rf "$d"
+
+d=$(_mktmp)
+printf 'title: Unrelated Site\n' > "$d/_config.yml"
+assert_false "validate_theme_connection '$d'" "no theme connection → 1"
+rm -rf "$d"
+
+# --- detect_version_gap ---------------------------------------------------
+echo "Testing detect_version_gap..."
+
+d=$(_mktmp)
+assert_true "detect_version_gap '$d'" "no Gemfile.lock → pass (cannot check)"
+
+printf '    jekyll-theme-zer0 (1.14.0)\n' > "$d/Gemfile.lock"
+assert_true "detect_version_gap '$d'" "modern version >= min → pass"
+
+printf '    jekyll-theme-zer0 (0.22.5)\n' > "$d/Gemfile.lock"
+assert_false "detect_version_gap '$d'" "version below 0.22.10 min → gap detected"
+rm -rf "$d"
+
+echo -e "\n${GREEN}migrate.sh tests complete${NC}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.17.1
+  version: 1.18.1
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -374,6 +374,7 @@ files:
 - scripts/bin/test
 - scripts/bin/validate
 - scripts/build
+- scripts/content-review.rb
 - scripts/convert-notebooks.sh
 - scripts/docker-publish
 - scripts/docs/check-freshness.sh
@@ -490,6 +491,7 @@ files:
 - scripts/test/lib/test_gem.sh
 - scripts/test/lib/test_git.sh
 - scripts/test/lib/test_locale_independence.sh
+- scripts/test/lib/test_migrate.sh
 - scripts/test/lib/test_validation.sh
 - scripts/test/lib/test_version.sh
 - scripts/test/theme/validate