jekyll-theme-zer0 1.22.0 → 1.24.0

data/scripts/issues/verify_close.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+verify_close.py — the deterministic gate of the Issue Autopilot verify-and-close lane.
+
+The issue-verifier (an LLM, read-only) inspects each `verify_candidate` issue and
+writes its verdicts to `.issues/verify.json`. This script is the DETERMINISTIC half:
+it selects which of those verdicts may actually close an issue, and it does so ONLY
+when `main`'s full CI/CD gate suite is green. The autopilot never closes a human
+issue on an LLM's say-so alone — the green-CI gate here is the hard backstop.
+
+A verdict closes its issue iff ALL of:
+  1. verdict.resolved is true,
+  2. verdict.confidence == "high" and verdict.evidence is non-empty,
+  3. the issue is a `verify_candidate` in plan.json (defense in depth — never a
+     protected/backlog-managed/bot/epic issue, even if the LLM names one),
+  4. `main`'s combined commit status + every check-run on its HEAD are green.
+
+`select` prints `<number>\t<evidence>` TSV for closable issues (the workflow does
+the actual `gh issue close`, keeping the irreversible mutation in an auditable
+step). If the CI/CD gate is not green, it prints NOTHING and the whole batch is
+held — "close only if they pass all CI/CD gates" is all-or-nothing per run.
+
+READ-ONLY against GitHub: this script only ever calls `gh api` GET endpoints. It
+never closes, comments, or labels. Verdict text is treated strictly as DATA.
+
+  Subcommands:
+    select   print closable `<number>\t<evidence>` lines (gated on green CI)
+    gate     print "green" / "not-green: <why>" for main's CI suite, then exit 0/1
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+ISSUES_DIR = Path(".issues")
+PLAN_PATH = ISSUES_DIR / "plan.json"
+VERIFY_PATH = ISSUES_DIR / "verify.json"
+
+# check-run conclusions that do NOT block a close (everything else does, and any
+# check-run that has not `completed` blocks too — something is still running).
+OK_CONCLUSIONS = {"success", "neutral", "skipped"}
+
+
+def warn(msg: str) -> None:
+    print(f"::warning::verify_close: {msg}", file=sys.stderr)
+
+
+def _gh_api(path: str) -> Optional[Any]:
+    """GET a gh api endpoint, returning parsed JSON or None on any failure."""
+    try:
+        out = subprocess.run(
+            ["gh", "api", "-H", "Accept: application/vnd.github+json", path],
+            capture_output=True, text=True, timeout=60,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        warn(f"gh api {path} failed to run: {exc}")
+        return None
+    if out.returncode != 0:
+        warn(f"gh api {path} exited {out.returncode}: {out.stderr.strip()[:200]}")
+        return None
+    try:
+        return json.loads(out.stdout or "null")
+    except json.JSONDecodeError as exc:
+        warn(f"gh api {path} returned non-JSON: {exc}")
+        return None
+
+
+def ci_gate(repo: str, ref: str = "main") -> tuple[bool, str]:
+    """
+    True iff `main`'s combined commit status AND every check-run on its HEAD are
+    green. Fails CLOSED: any API error, pending run, or failure -> (False, why).
+    """
+    if not repo:
+        return False, "no repo configured"
+
+    status = _gh_api(f"repos/{repo}/commits/{ref}/status")
+    if status is None:
+        return False, "could not read commit status (failing closed)"
+    state = str(status.get("state") or "")
+    total = int(status.get("total_count") or 0)
+    # A commit with zero classic statuses reports state=pending; that's only a
+    # blocker if there are actually statuses. With statuses, require success.
+    if total > 0 and state != "success":
+        return False, f"combined commit status is '{state}' ({total} status(es))"
+
+    runs = _gh_api(f"repos/{repo}/commits/{ref}/check-runs?per_page=100")
+    if runs is None:
+        return False, "could not read check-runs (failing closed)"
+    for run in runs.get("check_runs") or []:
+        name = str(run.get("name") or "?")
+        if str(run.get("status")) != "completed":
+            return False, f"check-run '{name}' is not completed (status={run.get('status')})"
+        if str(run.get("conclusion")) not in OK_CONCLUSIONS:
+            return False, f"check-run '{name}' concluded '{run.get('conclusion')}'"
+    return True, f"green (state={state or 'none'}, {total} status(es), all check-runs passed)"
+
+
+def _load(path: Path) -> Optional[Any]:
+    if not path.exists():
+        warn(f"{path} not found")
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        warn(f"{path} unreadable: {exc}")
+        return None
+
+
+def closable(plan: dict[str, Any], verify: dict[str, Any]) -> list[dict[str, Any]]:
+    """Verdicts that pass the policy filter (steps 1-3), before the CI gate."""
+    candidates = {
+        int(r["number"]): r
+        for r in (plan.get("issues") or [])
+        if r.get("verify_candidate") and r.get("number") is not None
+    }
+    out: list[dict[str, Any]] = []
+    for v in (verify.get("verdicts") or []):
+        try:
+            num = int(v.get("number"))
+        except (TypeError, ValueError):
+            continue
+        if not v.get("resolved"):
+            continue
+        if str(v.get("confidence") or "").lower() != "high":
+            continue
+        evidence = str(v.get("evidence") or "").strip()
+        if not evidence:
+            continue
+        if num not in candidates:  # defense in depth — never close a non-candidate
+            warn(f"#{num} verdict resolved but not a verify_candidate — skipping")
+            continue
+        out.append({"number": num, "evidence": evidence})
+    return out
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("command", choices=["select", "gate"])
+    ap.add_argument("--repo", default=None, help="owner/name (else from plan.json)")
+    ap.add_argument("--ref", default="main", help="git ref to gate on (default: main)")
+    args = ap.parse_args(argv)
+
+    plan = _load(PLAN_PATH) or {}
+    repo = args.repo or str(plan.get("repo") or "")
+
+    if args.command == "gate":
+        green, why = ci_gate(repo, args.ref)
+        print("green" if green else f"not-green: {why}")
+        return 0 if green else 1
+
+    # select
+    verify = _load(VERIFY_PATH)
+    if not isinstance(verify, dict):
+        print("no verdicts to act on.", file=sys.stderr)
+        return 0
+    picks = closable(plan, verify)
+    if not picks:
+        print("no resolved+high-confidence verdicts for a verify_candidate.", file=sys.stderr)
+        return 0
+
+    green, why = ci_gate(repo, args.ref)
+    if not green:
+        warn(f"CI/CD gate not green — holding {len(picks)} close(s) this run: {why}")
+        return 0
+
+    print(f"CI/CD gate {why}", file=sys.stderr)
+    for p in picks:
+        # TSV: the workflow closes these; evidence goes into the close comment.
+        evidence = p["evidence"].replace("\t", " ").replace("\n", " ")
+        print(f"{p['number']}\t{evidence}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/validate-features.rb

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# validate-features.rb — canonical integrity checker for the feature registry.
+#
+# Single source of truth shared by `scripts/bin/validate` (preflight) and
+# `test/test_features.sh` (the `features` test suite). Governance:
+# .github/instructions/features.instructions.md.
+#
+# HARD failures (exit 1):
+#   - features/features.yml and _data/features.yml are not byte-identical
+#   - the header is missing a `# Last Updated:` line
+#   - schema violations (missing required field, bad id/version, duplicate id)
+#   - implemented:false without `removed_in:`
+#   - a reference path on an ACTIVE feature does not exist in the repo
+#   - missing/malformed `provenance:` block on an active feature (since PR B)
+#   - missing/unresolvable `tests:` linkage on an active feature (since PR C):
+#     every entry must be a real test path or `{na: reason}`
+#
+# WARNINGS (non-fatal unless FEATURES_STRICT=1):
+#   - header `# Version:` not tracking the gem version
+#   - id gaps (IDs are never reused, but gaps are worth a human glance)
+#
+# Portable across Ruby 2.6 (macOS system) and 3.x (CI/Docker).
+# ---------------------------------------------------------------------------
+
+require 'date'
+require 'yaml'
+
+MASTER = 'features/features.yml'
+MIRROR = '_data/features.yml'
+REQUIRED = %w[id title description implemented version link docs tags date].freeze
+STRICT = ENV['FEATURES_STRICT'] == '1'
+
+def die(msg)
+  warn "  \e[31m✗\e[0m #{msg}"
+  exit 1
+end
+
+# Ruby 3.1+ defaults YAML.load_file to safe loading (rejects Date); 2.6 does
+# not accept the keywords. Try the strict form, fall back for old Ruby.
+def load_yaml(path)
+  YAML.load_file(path, permitted_classes: [Date, Time], aliases: true)
+rescue ArgumentError
+  YAML.load_file(path)
+end
+
+def ref_paths(refs)
+  return [] unless refs.is_a?(Hash)
+
+  refs.values.flat_map { |v| v.is_a?(Array) ? v : [v] }.select { |v| v.is_a?(String) }
+end
+
+[MASTER, MIRROR].each { |f| die "#{f} is missing" unless File.file?(f) }
+
+# 1. Sync contract — the two registries must be byte-identical.
+if File.binread(MASTER) != File.binread(MIRROR)
+  die "#{MASTER} and #{MIRROR} differ — run `cp #{MASTER} #{MIRROR}` (must be byte-identical)"
+end
+
+data = load_yaml(MIRROR)
+feats = data && data['features']
+die 'top-level `features:` list missing' unless feats.is_a?(Array)
+
+warnings = []
+
+# Header sanity.
+header = File.foreach(MIRROR).first(8).join
+gem_version = File.read('lib/jekyll-theme-zer0/version.rb')[/VERSION\s*=\s*"([^"]+)"/, 1]
+warnings << "header `# Version:` should match gem version #{gem_version}" unless header.include?("# Version: #{gem_version}")
+die 'header missing `# Last Updated: YYYY-MM-DD` line' unless header =~ /# Last Updated: \d{4}-\d{2}-\d{2}/
+
+seen = {}
+feats.each_with_index do |f, i|
+  die "entry ##{i} is not a mapping" unless f.is_a?(Hash)
+  id = f['id'] || "(index #{i})"
+
+  REQUIRED.each do |key|
+    val = f[key]
+    die "#{id}: required field `#{key}` is missing/empty" if val.nil? || (val.respond_to?(:empty?) && val.empty?)
+  end
+
+  die "#{id}: id must match ZER0-NNN" unless f['id'] =~ /\AZER0-\d{3}\z/
+  die "#{id}: duplicate id" if seen[f['id']]
+  seen[f['id']] = true
+  die "#{id}: version must be X.Y.Z" unless f['version'].to_s =~ /\A\d+\.\d+\.\d+/
+  die "#{id}: tags must be a non-empty list" unless f['tags'].is_a?(Array) && !f['tags'].empty?
+
+  if f['implemented'] == false
+    # Removed features keep their (now-absent) references for history but must
+    # record when they went away.
+    die "#{id}: implemented:false requires `removed_in:`" unless f['removed_in']
+    next
+  end
+
+  # 2. Every reference path on an active feature must exist.
+  ref_paths(f['references']).each do |p|
+    ok = p.end_with?('/') ? File.directory?(p) : File.exist?(p)
+    die "#{id}: reference path does not exist: #{p}" unless ok
+  end
+
+  # 3a. Provenance is REQUIRED on every active feature (backfilled in PR B).
+  prov = f['provenance']
+  die "#{id}: missing `provenance:` block" unless prov.is_a?(Hash)
+  die "#{id}: provenance.introduced_in must be a version string" unless prov['introduced_in'].is_a?(String) && prov['introduced_in'] =~ /\A\d+\.\d+\.\d+/
+  die "#{id}: provenance.commit must be a short git hash" unless prov['commit'].is_a?(String) && prov['commit'] =~ /\A[0-9a-f]{7,40}\z/
+  die "#{id}: provenance.pr must be an integer or null" unless prov['pr'].nil? || prov['pr'].is_a?(Integer)
+  die "#{id}: provenance.issue must be an integer or null" unless prov['issue'].nil? || prov['issue'].is_a?(Integer)
+
+  # 3b. Test linkage is REQUIRED on every active feature (backfilled in PR C).
+  tests = f['tests']
+  die "#{id}: missing/empty `tests:` (a real test path or `{na: reason}`)" unless tests.is_a?(Array) && !tests.empty?
+  tests.each do |t|
+    if t.is_a?(String)
+      die "#{id}: tests entry does not exist: #{t}" unless File.exist?(t)
+    elsif t.is_a?(Hash)
+      die "#{id}: tests `na:` must carry a non-empty reason" unless t['na'].is_a?(String) && !t['na'].strip.empty?
+    else
+      die "#{id}: tests entries must be a path string or `{na: reason}`"
+    end
+  end
+end
+
+# Sequential-id sanity (gaps allowed — never reuse an ID — but flagged).
+nums = seen.keys.map { |k| k.split('-').last.to_i }.sort
+gaps = (1..nums.last).to_a - nums
+warnings << "id gaps (verify intentional): #{gaps.map { |n| format('ZER0-%03d', n) }.join(', ')}" unless gaps.empty?
+
+unless warnings.empty?
+  verbose = STRICT || ENV['FEATURES_VERBOSE'] == '1'
+  prov  = warnings.count { |w| w.include?('provenance') }
+  tests = warnings.count { |w| w.include?('`tests:`') }
+  other = warnings.length - prov - tests
+  warn "  \e[33m⚠\e[0m feature registry: #{warnings.length} warning(s) — " \
+       "provenance:#{prov} tests:#{tests} other:#{other} (FEATURES_VERBOSE=1 for the full list)"
+  warnings.each { |w| warn "    - #{w}" } if verbose
+  die "#{warnings.length} warning(s) treated as errors (FEATURES_STRICT=1)" if STRICT
+end
+
+active = feats.count { |f| f['implemented'] != false }
+puts "Feature registry valid: #{feats.length} entries (#{active} active), refs resolved, master/_data in sync"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.22.0
+  version: 1.24.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -78,6 +78,7 @@ files:
 - LICENSE
 - README.md
 - _data/README.md
+- _data/ai.yml
 - _data/authors.yml
 - _data/backlog.yml
 - _data/content_statistics.yml
@@ -171,6 +172,7 @@ files:
 - _includes/content/toc.html
 - _includes/content/transclude.html
 - _includes/core/branding.html
+- _includes/core/color-mode-init.html
 - _includes/core/footer-fabs.html
 - _includes/core/footer.html
 - _includes/core/head.html
@@ -384,6 +386,7 @@ files:
 - scripts/bin/test
 - scripts/bin/validate
 - scripts/build
+- scripts/ci/classify_changes.py
 - scripts/content-review.rb
 - scripts/convert-notebooks.sh
 - scripts/dev/css-diff.sh
@@ -449,6 +452,10 @@ files:
 - scripts/install/template.sh
 - scripts/install/tui.sh
 - scripts/install/upgrade.sh
+- scripts/issues/dispatch.py
+- scripts/issues/test_verify_close.py
+- scripts/issues/triage.py
+- scripts/issues/verify_close.py
 - scripts/lib/README.md
 - scripts/lib/audit.sh
 - scripts/lib/changelog.sh
@@ -519,6 +526,7 @@ files:
 - scripts/utils/fix-markdown
 - scripts/utils/setup
 - scripts/validate
+- scripts/validate-features.rb
 - scripts/vendor-install.sh
 homepage: https://github.com/bamr87/zer0-mistakes
 licenses: