jekyll-theme-zer0 1.10.0 → 1.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e3dadf187dfaae9c1186aa1e0864f19ca74e9564cee0b0fa3136657fda6cf03
-  data.tar.gz: '024782a85ed83017188dac310e4aa75ed22f41d604576758f4f7f49564cba984'
+  metadata.gz: 98ca7799830fd5c793814a39656893d742627b0ce2800e32761ce53bc32b8263
+  data.tar.gz: 8b247e3c6002ec51bfc9c2c423f2cb531afa97f65c59b8c5526fe9251f70df22
 SHA512:
-  metadata.gz: 692271e54f6065325496b8bcfc9956194e085bd07d7a53f3c9adc108b146e846f712d126e5794b52cdbd1cad75e4dbfa91260767820fee2903894472b76af7a7
-  data.tar.gz: f0dd37b5871364845af1f663f41f59910f5e9e4ed2d5a6c3033fe56433f9f5006d8e99bcd3054c1f4352b542d9857232082c1a219d15a7cb5f1a1defedc72ecc
+  metadata.gz: f742ce6d82fdc8cb006f2604a8e8cb17927fd4991eea0817f69dceb9a8b4d1924e95c0f933dc50e5ea903b3abc81afb90cebd41ef26c942551c8561688a0ce03
+  data.tar.gz: ee9047c92ee91c57c357698f680c43de518c38db8c6b29c7133937009a5ec1ecfffd535f068449ef2969b449eeb91498dcaec57241b31980127bb32f6b76543d

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [1.11.1] - 2026-06-01
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- d4a53d51 docs: consolidate, standardize, and add maintenance system (#112)
+
+
+## [1.11.0] - 2026-06-01
+
+### Changed
+- Version bump: minor release
+
+### Commits in this release
+- 8a5ba7e2 feat(ci): add continuous-evolution backlog loop (#114)
+
+
+## [Unreleased]
+
+### Added
+- **Continuous-evolution loop**: a self-sustaining backlog mechanism so AI agents can keep improving the repo between human sessions.
+  - `_data/backlog.yml` — tactical task queue (single source of truth), mirroring the `_data/roadmap.yml` pattern.
+  - `scripts/sync-backlog.rb` (+ `scripts/sync-backlog.sh`) — schema validator and GitHub Issues sync (idempotent via `<!-- backlog-id -->` markers).
+  - `.github/workflows/backlog-sync.yml` — syncs the backlog to issues on push to `main`; validates schema on PRs.
+  - `.github/workflows/auto-merge.yml` — enables native auto-merge for low-risk (`docs`/`deps`/`lint`) PRs once CI is green.
+  - `.github/prompts/repo-audit.prompt.md` (`/repo-audit`) and `.github/prompts/backlog-implement.prompt.md` (`/backlog-implement`) — the audit and implement routines.
+  - `.github/instructions/backlog.instructions.md` — file-scoped guidance for the backlog.
+  - `docs/systems/continuous-evolution.md` — full design, autonomy policy, and setup.
+  - `CLAUDE.md` — Claude Code pointer to `AGENTS.md` (per the documented convention).
 ## [1.10.0] - 2026-06-01
 
 ### Changed

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.10.0
+version: 1.11.1
 layout: landing
 tags:
   - jekyll
@@ -20,7 +20,7 @@ categories:
   - bootstrap
   - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-06-01T03:29:07.000Z
+lastmod: 2026-06-01T13:28:14.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -901,7 +901,7 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 1.10.0 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 1.11.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/)) |
@@ -956,6 +956,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.10.0** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
+**v1.11.1** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
 
 

data/_data/backlog.yml

@@ -0,0 +1,161 @@
+# =============================================================================
+# zer0-mistakes Backlog — Tactical Task Queue (Single Source of Truth)
+# =============================================================================
+#
+# This file is the canonical, machine-readable backlog of *tactical* tasks
+# (the granular, pickup-able work items). It complements `_data/roadmap.yml`,
+# which holds the *strategic* milestones.
+#
+# It powers the continuous-evolution loop:
+#
+#   1. The AUDIT routine (`.github/prompts/repo-audit.prompt.md`) appends new
+#      tasks here when it reviews the repo.
+#   2. `scripts/sync-backlog.rb` (run by `.github/workflows/backlog-sync.yml`)
+#      mirrors each open task to a GitHub Issue and closes issues for tasks
+#      marked `done`.
+#   3. The IMPLEMENT routine (`.github/prompts/backlog-implement.prompt.md`)
+#      picks the highest-priority open task, implements it, and opens a PR.
+#
+# See `docs/systems/continuous-evolution.md` for the full design.
+#
+# To add a task by hand:
+#   1. Copy the schema block below; give it the next free `T-NNN` id.
+#   2. Set status/priority/area/risk/effort/source and acceptance criteria.
+#   3. Commit. The sync workflow creates the matching GitHub Issue on push.
+#
+# =============================================================================
+# Schema
+# =============================================================================
+#
+# meta:
+#   title:    Display title
+#   updated:  Last-reviewed date (YYYY-MM-DD)
+#   next_id:  Next free task id number (the audit routine increments this)
+#
+# tasks:
+#   - id:         Stable task id, "T-NNN" (never reused; matches the GitHub Issue)
+#     title:      One line — becomes the GitHub Issue title
+#     status:     open | in-progress | blocked | done
+#     priority:   P0 (urgent) | P1 | P2 | P3 (nice-to-have)
+#     area:       tests | docs | feat | infra | a11y | perf | deps | lint
+#     risk:       low (auto-merge eligible) | standard (human review required)
+#     effort:     S | M | L
+#     source:     audit | roadmap | issue | user
+#     summary:    1–2 lines of context
+#     acceptance: List of checkable done-criteria the implement routine verifies
+#     links:      { issue: <#|null>, pr: <#|null>, roadmap: "<version>|null" }
+#     created:    YYYY-MM-DD
+#     updated:    YYYY-MM-DD
+#
+# `risk: low` + area in {docs, deps, lint} makes a task auto-merge eligible once
+# CI is green (see `.github/prompts/backlog-implement.prompt.md`). Everything
+# else stays PR-only for human review.
+#
+# =============================================================================
+
+meta:
+  title: "zer0-mistakes Backlog"
+  updated: 2026-05-31
+  next_id: 7
+
+tasks:
+  # --- Housekeeping (seeded so the loop has work on day one) ------------------
+
+  - id: T-001
+    title: "Reconcile roadmap milestone numbering with the published gem version"
+    status: open
+    priority: P2
+    area: docs
+    risk: standard
+    effort: M
+    source: user
+    summary: >-
+      `_data/roadmap.yml` milestones run 0.17–1.0 while the gem ships as 1.9.9.
+      Decide on a single numbering scheme (or document the mapping) so the
+      roadmap, README, and RubyGems version no longer contradict each other.
+    acceptance:
+      - "Roadmap version line and gem version no longer contradict (either remapped or an explicit mapping note added to `_data/roadmap.yml` and `pages/roadmap.md`)."
+      - "`./scripts/generate-roadmap.sh --check` passes after the change."
+      - "No edit to `lib/jekyll-theme-zer0/version.rb`."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-05-31
+    updated: 2026-05-31
+
+  - id: T-002
+    title: "Refresh roadmap `updated:` date and review milestone statuses"
+    status: open
+    priority: P3
+    area: docs
+    risk: low
+    effort: S
+    source: user
+    summary: >-
+      `_data/roadmap.yml` `meta.updated` is 2026-04-18. Refresh it and confirm
+      the 0.22 "active" milestone still reflects reality.
+    acceptance:
+      - "`meta.updated` set to the current date."
+      - "Active/planned statuses reviewed against shipped work."
+      - "`./scripts/generate-roadmap.sh --check` passes."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-05-31
+    updated: 2026-05-31
+
+  - id: T-003
+    title: "Add GitHub issue templates and a pull-request template"
+    status: open
+    priority: P2
+    area: infra
+    risk: standard
+    effort: M
+    source: user
+    summary: >-
+      The repo has no `.github/ISSUE_TEMPLATE/` or PR template. Add a bug-report
+      and feature-request issue form plus a PR template that nudges contributors
+      toward conventional commits, CHANGELOG updates, and the test checklist.
+    acceptance:
+      - "`.github/ISSUE_TEMPLATE/bug_report.yml` and `feature_request.yml` exist and render."
+      - "`.github/pull_request_template.md` exists with a conventional-commit + CHANGELOG + tests checklist."
+      - "Agent-filed backlog issues remain compatible with the new templates (no broken automation)."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-05-31
+    updated: 2026-05-31
+
+  - id: T-004
+    title: "Docs-freshness sweep: reconcile docs/ ↔ pages/_docs/ and fix broken links"
+    status: open
+    priority: P2
+    area: docs
+    risk: low
+    effort: M
+    source: user
+    summary: >-
+      Run the markdown-link checker and audit the two-tier docs for drift,
+      stale dates/versions, and any user/technical pages that fell out of sync
+      after the recent alignment commit.
+    acceptance:
+      - "`markdown-link-check` (config in `.github/config/`) reports no broken internal links."
+      - "Any stale version/date references in `docs/` and `pages/_docs/` are corrected."
+      - "Cross-links between the user tier and technical tier resolve both ways."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-05-31
+    updated: 2026-05-31
+
+  - id: T-005
+    title: "Coverage baseline: identify the lowest-covered subsystems toward the v1.0 90% goal"
+    status: open
+    priority: P1
+    area: tests
+    risk: standard
+    effort: L
+    source: roadmap
+    summary: >-
+      The v1.0 milestone targets 90%+ automated test coverage. Produce a
+      coverage baseline and file follow-up tasks for the lowest-covered areas
+      (start with the modular installer and the Obsidian resolver paths).
+    acceptance:
+      - "A coverage baseline is recorded (test/coverage or a docs note)."
+      - "The 2–3 lowest-covered subsystems are identified and filed as new backlog tasks."
+      - "No reduction in existing passing tests (`./scripts/bin/test` stays green)."
+    links: { issue: null, pr: null, roadmap: "1.0" }
+    created: 2026-05-31
+    updated: 2026-05-31

data/_includes/components/theme-preview-gallery.html

@@ -442,7 +442,7 @@ docker-compose up
       <div class="card-body d-flex flex-column gap-4">
         <div>
           <p class="small text-body-secondary mb-1">Breadcrumb</p>
-          <nav aria-label="breadcrumb">
+          <nav aria-label="Breadcrumb example">
             <ol class="breadcrumb mb-0">
               <li class="breadcrumb-item"><a href="#">Home</a></li>
               <li class="breadcrumb-item"><a href="#">Settings</a></li>

data/scripts/docs/check-freshness.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/check-freshness.sh — Staleness detector for docs/
+# =========================================================================
+# Flags docs where the lastmod front matter field is more than THRESHOLD
+# days behind the file's most recent git commit. This surfaces docs that
+# describe code that has since changed without a corresponding doc update.
+#
+# Usage:
+#   ./scripts/docs/check-freshness.sh
+#   ./scripts/docs/check-freshness.sh --threshold 90   # custom days (default: 60)
+#   ./scripts/docs/check-freshness.sh --verbose
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+source "$SCRIPT_DIR/../lib/frontmatter.sh"
+
+THRESHOLD_DAYS=60
+STALE_COUNT=0
+FILES_CHECKED=0
+STALE_FILES=""
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --threshold) shift; THRESHOLD_DAYS="$1" ;;
+            --verbose)   export VERBOSE=true ;;
+            --help|-h)   show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << EOF
+Freshness Checker for docs/
+
+USAGE:
+    ./scripts/docs/check-freshness.sh [OPTIONS]
+
+OPTIONS:
+    --threshold N   Days of drift before flagging as stale (default: $THRESHOLD_DAYS)
+    --verbose       Show all files, not just stale ones
+
+A doc is stale when:
+  git log -1 date for that file > (lastmod front matter + THRESHOLD days)
+
+This catches docs describing code that changed but whose lastmod wasn't updated.
+EOF
+}
+
+# Returns seconds since epoch for a date string, or empty on failure
+date_to_epoch() {
+    local d="$1"
+    ruby -rtime -e "puts Time.parse('$d').to_i" 2>/dev/null || true
+}
+
+parse_args "$@"
+
+THRESHOLD_SECS=$(( THRESHOLD_DAYS * 86400 ))
+
+log "Checking freshness of docs (threshold: ${THRESHOLD_DAYS} days)..."
+echo ""
+
+for filepath in $(find "$REPO_ROOT/docs" -name "*.md" -not -name "README.md" -not -path "*/archive/*" | sort); do
+    relpath="${filepath#$REPO_ROOT/}"
+
+    # Skip files without front matter
+    local_first=""
+    IFS= read -r local_first < "$filepath" || true
+    if [[ ! "$local_first" =~ ^--- ]]; then
+        debug "  SKIP (no front matter): $relpath"
+        continue
+    fi
+
+    lastmod_str="$(get_frontmatter_field "$filepath" "lastmod" 2>/dev/null || true)"
+    if [[ -z "$lastmod_str" ]]; then
+        debug "  SKIP (no lastmod field): $relpath"
+        continue
+    fi
+
+    lastmod_epoch="$(date_to_epoch "$lastmod_str")"
+    [[ -z "$lastmod_epoch" ]] && continue
+
+    # Get last git commit date for this file
+    git_date_str="$(git -C "$REPO_ROOT" log -1 --format="%aI" -- "$relpath" 2>/dev/null || true)"
+    [[ -z "$git_date_str" ]] && continue
+
+    git_epoch="$(date_to_epoch "$git_date_str")"
+    [[ -z "$git_epoch" ]] && continue
+
+    drift=$(( git_epoch - lastmod_epoch ))
+
+    if [[ $drift -gt $THRESHOLD_SECS ]]; then
+        drift_days=$(( drift / 86400 ))
+        warn "  STALE (${drift_days}d behind): $relpath"
+        warn "         lastmod: $lastmod_str"
+        warn "         git:     $git_date_str"
+        STALE_FILES="$STALE_FILES $relpath"
+        STALE_COUNT=$((STALE_COUNT + 1))
+    else
+        debug "  FRESH: $relpath"
+    fi
+
+    FILES_CHECKED=$((FILES_CHECKED + 1))
+done
+
+echo ""
+log "Results: $FILES_CHECKED files checked, $STALE_COUNT stale"
+
+if [[ $STALE_COUNT -gt 0 ]]; then
+    echo ""
+    info "Stale files (update lastmod after reviewing content):"
+    for f in $STALE_FILES; do
+        echo "  - $f"
+    done
+    exit 1
+fi

data/scripts/docs/check-links.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/check-links.sh — Internal link checker for docs/
+# =========================================================================
+# Validates that relative markdown links in docs/**/*.md resolve to files
+# that actually exist in the repository. Does not validate external URLs.
+#
+# Usage:
+#   ./scripts/docs/check-links.sh
+#   ./scripts/docs/check-links.sh --verbose
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+
+ERRORS=0
+FILES_CHECKED=0
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --verbose) export VERBOSE=true ;;
+            --help|-h) show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << 'EOF'
+Internal Link Checker for docs/
+
+USAGE:
+    ./scripts/docs/check-links.sh [--verbose]
+
+Checks relative markdown links ([text](path)) in docs/**/*.md to verify
+the target file exists. The contributor docs under docs/ use filesystem
+relative links between markdown files, so they can be resolved on disk.
+
+Not covered here:
+  - pages/_docs/**: the user-facing Jekyll site uses permalink URLs and
+    the relative_url filter, which are not filesystem paths; those links
+    are validated by htmlproofer against the built _site in CI.
+  - External URLs (http://, https://, mailto:, etc.)
+  - Anchor-only links (#section)
+  - Absolute site URLs (/docs/..., /faq/, ...)
+EOF
+}
+
+# Extract relative markdown links from a file, excluding external, anchor-only,
+# and absolute site URLs. Uses Ruby (already required by this repo) so the
+# extraction is portable across GNU and BSD/macOS environments.
+extract_relative_links() {
+    local filepath="$1"
+    ruby -e '
+        in_fence = false
+        File.foreach(ARGV[0], encoding: "UTF-8") do |line|
+            # Toggle fenced code blocks (``` or ~~~); skip their contents,
+            # which are examples rather than real links.
+            if line =~ /\A\s*(```|~~~)/
+                in_fence = !in_fence
+                next
+            end
+            next if in_fence
+            # Ignore inline code spans so `[x](y)` written as code is skipped.
+            scrubbed = line.gsub(/`[^`]*`/, "")
+            scrubbed.scan(/\]\(([^)]+)\)/) do |m|
+                link = m[0].strip
+                next if link.empty?
+                next if link.include?("{{") || link.include?("{%")  # Liquid template
+                next if link =~ %r{\A[a-z][a-z0-9+.-]*:}i            # scheme: http:, mailto:, etc.
+                next if link.start_with?("#")                        # anchor-only
+                next if link.start_with?("/")                        # absolute site URL (Jekyll permalink)
+                link = link.split("#", 2).first                      # strip anchor fragment
+                puts link unless link.nil? || link.empty?
+            end
+        end
+    ' "$filepath" 2>/dev/null || true
+}
+
+parse_args "$@"
+
+log "Checking internal links in docs/..."
+echo ""
+
+# archive/ holds superseded historical docs; templates/ holds scaffolding with
+# intentional placeholder links (link-to-config, etc.) — neither is "live" docs.
+for filepath in $(find "$REPO_ROOT/docs" -name "*.md" \
+        -not -path "*/archive/*" -not -path "*/templates/*" 2>/dev/null | sort); do
+    relpath="${filepath#$REPO_ROOT/}"
+    filedir="$(dirname "$filepath")"
+    file_errors=0
+
+    while IFS= read -r link; do
+        [[ -z "$link" ]] && continue
+
+        # Resolve relative to the file's directory (absolute site URLs are
+        # filtered out in extract_relative_links)
+        target="$filedir/$link"
+
+        # Normalize (remove ./ and resolve ..)
+        target="$(cd "$(dirname "$target")" 2>/dev/null && pwd)/$(basename "$target")" 2>/dev/null || target="$filedir/$link"
+
+        if [[ ! -f "$target" && ! -d "$target" ]]; then
+            warn "  BROKEN: $relpath → $link"
+            file_errors=$((file_errors + 1))
+            ERRORS=$((ERRORS + 1))
+        else
+            debug "  OK: $relpath → $link"
+        fi
+    done < <(extract_relative_links "$filepath")
+
+    FILES_CHECKED=$((FILES_CHECKED + 1))
+done
+
+echo ""
+log "Results: $FILES_CHECKED files checked, $ERRORS broken links"
+
+[[ $ERRORS -eq 0 ]] || exit 1

data/scripts/docs/lint-frontmatter.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/lint-frontmatter.sh — Front matter validator for docs/
+# =========================================================================
+# Checks every content .md file under docs/ (excluding READMEs and archive/)
+# for the required front matter fields defined in the schema.
+#
+# Usage:
+#   ./scripts/docs/lint-frontmatter.sh           # validate
+#   ./scripts/docs/lint-frontmatter.sh --fix     # inject skeleton where missing
+#   ./scripts/docs/lint-frontmatter.sh --verbose # show per-file results
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+source "$SCRIPT_DIR/../lib/frontmatter.sh"
+
+FIX_MODE=false
+REQUIRED_FIELDS=(title description date lastmod categories tags author)
+ERRORS=0
+FILES_OK=0
+FILES_MISSING=0
+
+# Bash 3.2-compatible file-list builder (no mapfile)
+list_docs_files() {
+    find "$REPO_ROOT/docs" -name "*.md" \
+        -not -name "README.md" \
+        -not -path "*/archive/*" \
+        | sort
+}
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --fix)     FIX_MODE=true ;;
+            --verbose) export VERBOSE=true ;;
+            --help|-h) show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << 'EOF'
+Front Matter Linter for docs/
+
+USAGE:
+    ./scripts/docs/lint-frontmatter.sh [OPTIONS]
+
+REQUIRED FIELDS (per .github/instructions/documentation.instructions.md):
+    title, description, date, lastmod, categories, tags, author
+
+EXCLUDES:
+    - README.md files (directory indexes)
+    - docs/archive/** (historical docs)
+EOF
+}
+
+# Determine tags from directory name
+dir_tags() {
+    local dir="$1"
+    case "$dir" in
+        ui)             echo "[ui, styling, theme]" ;;
+        architecture)   echo "[architecture, design]" ;;
+        development)    echo "[development, contributing]" ;;
+        systems)        echo "[systems, automation]" ;;
+        installation)   echo "[installation, setup]" ;;
+        features)       echo "[features]" ;;
+        implementation) echo "[implementation, changelog]" ;;
+        releases)       echo "[releases]" ;;
+        templates)      echo "[templates]" ;;
+        *)              echo "[docs]" ;;
+    esac
+}
+
+# Inject skeleton front matter at the top of a file
+inject_frontmatter() {
+    local filepath="$1"
+    local relpath="${filepath#$REPO_ROOT/}"
+    local subdir
+    subdir="$(echo "$relpath" | cut -d'/' -f2)"
+
+    # Extract title from first H1 heading
+    local title
+    title="$(grep -m1 "^# " "$filepath" 2>/dev/null | sed 's/^# //' || true)"
+    [[ -z "$title" ]] && title="$(basename "$filepath" .md | tr '-' ' ' | sed 's/\b./\u&/g')"
+
+    # Dates from git history
+    local date lastmod now
+    now="$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")"
+    date="$(git -C "$REPO_ROOT" log --diff-filter=A --follow --format="%aI" -- "$relpath" 2>/dev/null | tail -1 || true)"
+    lastmod="$(git -C "$REPO_ROOT" log -1 --format="%aI" -- "$relpath" 2>/dev/null || true)"
+    [[ -z "$date" ]]    && date="$now"
+    [[ -z "$lastmod" ]] && lastmod="$now"
+
+    # Normalize to ISO 8601 with milliseconds
+    date="$(echo "$date" | ruby -rtime -e 'puts Time.parse(STDIN.read.strip).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")' 2>/dev/null || echo "$now")"
+    lastmod="$(echo "$lastmod" | ruby -rtime -e 'puts Time.parse(STDIN.read.strip).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")' 2>/dev/null || echo "$now")"
+
+    local tags
+    tags="$(dir_tags "$subdir")"
+
+    local skeleton
+    skeleton="---
+title: \"${title}\"
+description: \"TODO: Add a 120-160 character description of this document.\"
+date: ${date}
+lastmod: ${lastmod}
+categories: [docs]
+tags: ${tags}
+author: bamr87
+---"
+
+    # Prepend skeleton to file
+    local tmpfile
+    tmpfile="$(mktemp)"
+    printf '%s\n\n' "$skeleton" | cat - "$filepath" > "$tmpfile"
+    mv "$tmpfile" "$filepath"
+    info "  Injected front matter: $relpath"
+}
+
+parse_args "$@"
+
+total_files=0
+for f in $(list_docs_files); do total_files=$((total_files + 1)); done
+log "Checking $total_files docs files for required front matter..."
+echo ""
+
+for filepath in $(list_docs_files); do
+    relpath="${filepath#$REPO_ROOT/}"
+    missing=()
+
+    # Check if front matter exists at all
+    local_first_line=""
+    IFS= read -r local_first_line < "$filepath" || true
+
+    if [[ ! "$local_first_line" =~ ^--- ]]; then
+        if [[ "$FIX_MODE" == "true" ]]; then
+            inject_frontmatter "$filepath"
+            FILES_OK=$((FILES_OK + 1))
+            continue
+        else
+            warn "  MISSING front matter: $relpath"
+            FILES_MISSING=$((FILES_MISSING + 1))
+            ERRORS=$((ERRORS + 1))
+            continue
+        fi
+    fi
+
+    # Check each required field
+    fm="$(extract_frontmatter "$filepath" 2>/dev/null || true)"
+    missing_list=""
+    for field in "${REQUIRED_FIELDS[@]}"; do
+        if ! echo "$fm" | grep -q "^${field}:"; then
+            missing_list="$missing_list $field"
+        fi
+    done
+
+    # Description quality: presence alone is not enough. Reject the --fix
+    # skeleton placeholder and obvious stubs so a "compliant" run can't ship
+    # docs with a TODO description. Schema target is a 120-160 char sentence.
+    desc_problem=""
+    if echo "$fm" | grep -q "^description:"; then
+        desc_value="$(echo "$fm" | grep -m1 "^description:" | sed -E 's/^description:[[:space:]]*//; s/^"(.*)"$/\1/; s/^'"'"'(.*)'"'"'$/\1/')"
+        if echo "$desc_value" | grep -qi "TODO"; then
+            desc_problem="placeholder TODO description"
+        elif [[ "${#desc_value}" -lt 40 ]]; then
+            desc_problem="description too short (${#desc_value} chars; aim for 120-160)"
+        fi
+    fi
+
+    if [[ -n "$missing_list" || -n "$desc_problem" ]]; then
+        local_msg="  INCOMPLETE ($relpath):"
+        [[ -n "$missing_list" ]] && local_msg="$local_msg missing:$missing_list"
+        [[ -n "$desc_problem" ]] && local_msg="$local_msg $desc_problem"
+        warn "$local_msg"
+        ERRORS=$((ERRORS + 1))
+    else
+        debug "  OK: $relpath"
+        FILES_OK=$((FILES_OK + 1))
+    fi
+done
+
+incomplete=$((ERRORS - FILES_MISSING))
+echo ""
+log "Results: ${FILES_OK} OK, ${FILES_MISSING} missing front matter, ${incomplete} incomplete"
+
+if [[ $ERRORS -gt 0 ]]; then
+    if [[ "$FIX_MODE" == "false" ]]; then
+        info "Run with --fix to inject skeleton front matter into missing files."
+    fi
+    exit 1
+fi

data/scripts/docs/validate.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/validate.sh — Docs validation orchestrator
+# =========================================================================
+# Runs all docs health checks: front matter, links, and freshness.
+#
+# Usage:
+#   ./scripts/docs/validate.sh              # run all checks
+#   ./scripts/docs/validate.sh --lint       # front matter only
+#   ./scripts/docs/validate.sh --links      # links only
+#   ./scripts/docs/validate.sh --freshness  # freshness only
+#   ./scripts/docs/validate.sh --fix        # inject missing front matter
+#   ./scripts/docs/validate.sh --verbose    # detailed output
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+
+RUN_LINT=true
+RUN_LINKS=true
+RUN_FRESHNESS=true
+FIX_MODE=false
+OVERALL_STATUS=0
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --lint)       RUN_LINKS=false; RUN_FRESHNESS=false ;;
+            --links)      RUN_LINT=false;  RUN_FRESHNESS=false ;;
+            --freshness)  RUN_LINT=false;  RUN_LINKS=false ;;
+            --fix)        FIX_MODE=true ;;
+            --verbose)    export VERBOSE=true ;;
+            --help|-h)    show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << 'EOF'
+Docs Validation Suite for zer0-mistakes
+
+USAGE:
+    ./scripts/docs/validate.sh [OPTIONS]
+
+OPTIONS:
+    --lint        Front matter compliance only
+    --links       Link checking only
+    --freshness   Staleness check only
+    --fix         Inject skeleton front matter into files that lack it
+    --verbose     Detailed output
+    --help        Show this message
+
+CHECKS:
+    lint        Every docs/**/*.md (non-README, non-archive) has required
+                front matter: title, description, date, lastmod, categories,
+                tags, author
+    links       Internal markdown links resolve to existing files
+    freshness   Files where lastmod trails the last git commit by > 60 days
+EOF
+}
+
+run_check() {
+    local name="$1"; local script="$2"; shift 2
+    log "Running: $name"
+    if "$script" "$@"; then
+        log "  PASS: $name"
+    else
+        warn "  FAIL: $name"
+        OVERALL_STATUS=1
+    fi
+}
+
+parse_args "$@"
+
+[[ "$FIX_MODE" == "true" ]] && EXTRA="--fix" || EXTRA=""
+
+[[ "$RUN_LINT"      == "true" ]] && run_check "Front matter lint" "$SCRIPT_DIR/lint-frontmatter.sh" $EXTRA
+[[ "$RUN_LINKS"     == "true" ]] && run_check "Link check"        "$SCRIPT_DIR/check-links.sh"
+[[ "$RUN_FRESHNESS" == "true" ]] && run_check "Freshness check"   "$SCRIPT_DIR/check-freshness.sh"
+
+if [[ $OVERALL_STATUS -eq 0 ]]; then
+    log "All docs checks passed."
+else
+    error "One or more docs checks failed."
+    exit 1
+fi

data/scripts/sync-backlog.rb

@@ -0,0 +1,309 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# sync-backlog.rb
+# =============================================================================
+#
+# Mirrors `_data/backlog.yml` (the tactical task queue) to GitHub Issues.
+#
+#   - Each task with status open|in-progress|blocked  -> an OPEN issue.
+#   - Each task with status done                       -> its issue is CLOSED.
+#
+# Issues are matched back to tasks idempotently by a hidden marker embedded in
+# the issue body: `<!-- backlog-id: T-001 -->`. Re-running the sync updates the
+# title/body/labels in place rather than creating duplicates.
+#
+# Managed labels (created with `gh label create --force` if missing):
+#   agent-ready · priority:P0..P3 · area:<area> · risk:<low|standard> · agent-hold
+#
+# Usage:
+#   ruby scripts/sync-backlog.rb            # create/update/close issues via `gh`
+#   ruby scripts/sync-backlog.rb --check    # validate schema only (no `gh`, CI/PR gate)
+#   ruby scripts/sync-backlog.rb --dry-run  # print intended `gh` calls, make no changes
+#
+# Requires the `gh` CLI authenticated with `issues: write` for the write path.
+# `--check` needs only Ruby stdlib (used as the pull-request gate).
+# =============================================================================
+
+require 'yaml'
+require 'date'
+require 'json'
+require 'optparse'
+require 'open3'
+require 'shellwords'
+
+ROOT      = File.expand_path('..', __dir__)
+DATA_FILE = File.join(ROOT, '_data', 'backlog.yml')
+
+VALID_STATUS   = %w[open in-progress blocked done].freeze
+VALID_PRIORITY = %w[P0 P1 P2 P3].freeze
+VALID_AREA     = %w[tests docs feat infra a11y perf deps lint].freeze
+VALID_RISK     = %w[low standard].freeze
+VALID_EFFORT   = %w[S M L].freeze
+VALID_SOURCE   = %w[audit roadmap issue user].freeze
+
+OPEN_STATUSES = %w[open in-progress blocked].freeze
+
+# Labels this script owns. On each sync we reconcile a task's labels to exactly
+# the managed set it should carry, leaving any human-applied labels untouched.
+def managed_labels(task)
+  labels = ['agent-ready', "priority:#{task['priority']}", "area:#{task['area']}", "risk:#{task['risk']}"]
+  labels << 'agent-hold' if task['status'] == 'blocked'
+  labels
+end
+
+ALL_MANAGED_LABELS = (
+  ['agent-ready', 'agent-hold'] +
+  VALID_PRIORITY.map { |p| "priority:#{p}" } +
+  VALID_AREA.map { |a| "area:#{a}" } +
+  VALID_RISK.map { |r| "risk:#{r}" }
+).freeze
+
+LABEL_COLORS = {
+  'agent-ready' => '0e8a16',
+  'agent-hold'  => 'b60205'
+}.freeze
+PRIORITY_COLOR = 'd93f0b'
+AREA_COLOR     = '1d76db'
+RISK_COLOR     = 'fbca04'
+
+# ---------------------------------------------------------------------------
+# Load + validate
+# ---------------------------------------------------------------------------
+
+def load_data
+  # Mirror generate-roadmap.rb: permit Date/Time, and fall back for the older
+  # macOS system Ruby (2.6) whose safe loader signature differs.
+  begin
+    YAML.load_file(DATA_FILE, permitted_classes: [Date, Time])
+  rescue ArgumentError
+    YAML.safe_load(File.read(DATA_FILE), permitted_classes: [Date, Time], aliases: false)
+  end
+end
+
+def validate(data)
+  errors = []
+  errors << 'Missing top-level `meta:` mapping.' unless data.is_a?(Hash) && data['meta'].is_a?(Hash)
+  tasks = data.is_a?(Hash) ? data['tasks'] : nil
+  return ['Missing or empty `tasks:` list.'] unless tasks.is_a?(Array) && !tasks.empty?
+
+  seen_ids = {}
+  tasks.each_with_index do |task, i|
+    where = "tasks[#{i}]"
+    unless task.is_a?(Hash)
+      errors << "#{where}: each task must be a mapping."
+      next
+    end
+    id = task['id']
+    where = id ? "task #{id}" : where
+    errors << "#{where}: missing `id`." if id.to_s.empty?
+    errors << "#{where}: `id` must match T-NNN (got #{id.inspect})." if id && id !~ /\AT-\d{3,}\z/
+    if id && seen_ids[id]
+      errors << "#{where}: duplicate id #{id} (also at #{seen_ids[id]})."
+    elsif id
+      seen_ids[id] = where
+    end
+    errors << "#{where}: missing `title`." if task['title'].to_s.strip.empty?
+    check_enum(errors, where, task, 'status', VALID_STATUS)
+    check_enum(errors, where, task, 'priority', VALID_PRIORITY)
+    check_enum(errors, where, task, 'area', VALID_AREA)
+    check_enum(errors, where, task, 'risk', VALID_RISK)
+    check_enum(errors, where, task, 'effort', VALID_EFFORT) if task['effort']
+    check_enum(errors, where, task, 'source', VALID_SOURCE) if task['source']
+    unless task['acceptance'].is_a?(Array) && !task['acceptance'].empty?
+      errors << "#{where}: `acceptance` must be a non-empty list."
+    end
+  end
+  errors
+end
+
+def check_enum(errors, where, task, field, allowed)
+  value = task[field]
+  return if allowed.include?(value)
+
+  errors << "#{where}: `#{field}` must be one of #{allowed.join('|')} (got #{value.inspect})."
+end
+
+# ---------------------------------------------------------------------------
+# Issue body rendering
+# ---------------------------------------------------------------------------
+
+def marker(id)
+  "<!-- backlog-id: #{id} -->"
+end
+
+def render_body(task)
+  accept = (task['acceptance'] || []).map { |a| "- [ ] #{a}" }.join("\n")
+  roadmap = task.dig('links', 'roadmap')
+  meta_row = [
+    "**Priority:** #{task['priority']}",
+    "**Area:** #{task['area']}",
+    "**Risk:** #{task['risk']}",
+    "**Effort:** #{task['effort']}",
+    "**Source:** #{task['source']}"
+  ].join(' · ')
+
+  <<~BODY.strip
+    #{marker(task['id'])}
+    > Auto-managed from [`_data/backlog.yml`](../blob/main/_data/backlog.yml) by `scripts/sync-backlog.rb`.
+    > Edit the backlog file, not this issue body — changes here are overwritten on the next sync.
+
+    #{meta_row}#{roadmap ? " · **Roadmap:** v#{roadmap}" : ''}
+
+    #{task['summary'].to_s.strip}
+
+    ## Acceptance criteria
+
+    #{accept}
+
+    ---
+    Picked up by the IMPLEMENT routine (`.github/prompts/backlog-implement.prompt.md`).
+    See [`docs/systems/continuous-evolution.md`](../blob/main/docs/systems/continuous-evolution.md).
+  BODY
+end
+
+# ---------------------------------------------------------------------------
+# gh helpers
+# ---------------------------------------------------------------------------
+
+class Gh
+  def initialize(dry_run:)
+    @dry_run = dry_run
+  end
+
+  # Read-only call. Always executed (even in dry-run) so we can compute a diff;
+  # degrades to a default value if `gh` is unavailable/unauthenticated.
+  def read(args, default:)
+    out, _err, status = Open3.capture3('gh', *args)
+    return default unless status.success?
+
+    out
+  rescue Errno::ENOENT
+    default
+  end
+
+  # Mutating call. Printed (not executed) in dry-run mode.
+  def write(args)
+    if @dry_run
+      puts "DRY-RUN gh #{args.map { |a| a.to_s.include?(' ') ? a.inspect : a }.join(' ')}"
+      return true
+    end
+    _out, err, status = Open3.capture3('gh', *args)
+    warn "gh #{args.first} failed: #{err.strip}" unless status.success?
+    status.success?
+  end
+end
+
+def ensure_labels(gh)
+  LABEL_COLORS.each { |name, color| gh.write(['label', 'create', name, '--color', color, '--force']) }
+  VALID_PRIORITY.each { |p| gh.write(['label', 'create', "priority:#{p}", '--color', PRIORITY_COLOR, '--force']) }
+  VALID_AREA.each { |a| gh.write(['label', 'create', "area:#{a}", '--color', AREA_COLOR, '--force']) }
+  VALID_RISK.each { |r| gh.write(['label', 'create', "risk:#{r}", '--color', RISK_COLOR, '--force']) }
+end
+
+# Map of backlog id -> existing issue {number, state, labels} via the body marker.
+def existing_issues(gh)
+  raw = gh.read(
+    ['issue', 'list', '--label', 'agent-ready', '--state', 'all', '--limit', '500',
+     '--json', 'number,body,state,labels'],
+    default: '[]'
+  )
+  index = {}
+  JSON.parse(raw).each do |issue|
+    next unless issue['body'] =~ /<!-- backlog-id: (T-\d+) -->/
+
+    index[Regexp.last_match(1)] = {
+      'number' => issue['number'],
+      'state'  => issue['state'].to_s.downcase,
+      'labels' => (issue['labels'] || []).map { |l| l['name'] }
+    }
+  end
+  index
+rescue JSON::ParserError
+  {}
+end
+
+# ---------------------------------------------------------------------------
+# Sync
+# ---------------------------------------------------------------------------
+
+def label_args(desired, current)
+  desired_set = desired
+  # Only remove labels we manage; never touch human-applied ones.
+  to_remove = (current & ALL_MANAGED_LABELS) - desired_set
+  to_add    = desired_set - current
+  args = []
+  to_add.each    { |l| args.push('--add-label', l) }
+  to_remove.each { |l| args.push('--remove-label', l) }
+  args
+end
+
+def sync(data, gh)
+  ensure_labels(gh)
+  index = existing_issues(gh)
+  created = updated = closed = 0
+
+  (data['tasks'] || []).each do |task|
+    id    = task['id']
+    title = task['title']
+    body  = render_body(task)
+    want_open = OPEN_STATUSES.include?(task['status'])
+    issue = index[id]
+
+    if issue.nil?
+      next unless want_open # never create an issue for an already-done task
+
+      args = ['issue', 'create', '--title', title, '--body', body]
+      managed_labels(task).each { |l| args.push('--label', l) }
+      created += 1 if gh.write(args)
+      next
+    end
+
+    number = issue['number'].to_s
+    gh.write(['issue', 'edit', number, '--title', title, '--body', body] +
+             label_args(managed_labels(task), issue['labels']))
+    updated += 1
+
+    if want_open && issue['state'] != 'open'
+      gh.write(['issue', 'reopen', number])
+    elsif !want_open && issue['state'] != 'closed'
+      gh.write(['issue', 'close', number, '--reason', 'completed'])
+      closed += 1
+    end
+  end
+
+  puts "Backlog sync complete: #{created} created, #{updated} updated, #{closed} closed."
+  0
+end
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main
+  mode = :sync
+  OptionParser.new do |opts|
+    opts.banner = 'Usage: sync-backlog.rb [--check|--dry-run]'
+    opts.on('--check', 'Validate schema only; make no gh calls') { mode = :check }
+    opts.on('--dry-run', 'Print intended gh calls without executing') { mode = :dry_run }
+  end.parse!
+
+  data = load_data
+  errors = validate(data)
+  unless errors.empty?
+    warn '✗ _data/backlog.yml failed validation:'
+    errors.each { |e| warn "  - #{e}" }
+    return 1
+  end
+  task_count = (data['tasks'] || []).size
+
+  if mode == :check
+    puts "✓ _data/backlog.yml is valid (#{task_count} tasks)."
+    return 0
+  end
+
+  sync(data, Gh.new(dry_run: mode == :dry_run))
+end
+
+exit main if $PROGRAM_NAME == __FILE__

data/scripts/sync-backlog.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# =============================================================================
+# sync-backlog.sh
+# =============================================================================
+#
+# Thin wrapper around scripts/sync-backlog.rb.
+#
+# Mirrors `_data/backlog.yml` (the tactical task queue) to GitHub Issues:
+# open tasks become open issues; tasks marked `done` close their issue.
+#
+# Usage:
+#   ./scripts/sync-backlog.sh             # create/update/close issues via gh
+#   ./scripts/sync-backlog.sh --check     # validate schema only (CI/PR gate)
+#   ./scripts/sync-backlog.sh --dry-run   # print intended gh calls only
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec ruby "${SCRIPT_DIR}/sync-backlog.rb" "$@"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.1
 platform: ruby
 authors:
 - Amr Abdel
@@ -79,6 +79,7 @@ files:
 - README.md
 - _data/README.md
 - _data/authors.yml
+- _data/backlog.yml
 - _data/content_statistics.yml
 - _data/features.yml
 - _data/generate_statistics.rb
@@ -367,6 +368,10 @@ files:
 - scripts/build
 - scripts/convert-notebooks.sh
 - scripts/docker-publish
+- scripts/docs/check-freshness.sh
+- scripts/docs/check-links.sh
+- scripts/docs/lint-frontmatter.sh
+- scripts/docs/validate.sh
 - scripts/example-usage.sh
 - scripts/features/generate-preview-images
 - scripts/features/install-preview-generator
@@ -462,6 +467,8 @@ files:
 - scripts/post-template-setup.sh
 - scripts/release
 - scripts/setup.sh
+- scripts/sync-backlog.rb
+- scripts/sync-backlog.sh
 - scripts/test-auto-version.sh
 - scripts/test-mermaid.sh
 - scripts/test-notebook-conversion.sh