jekyll-theme-zer0 1.20.2 → 1.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2871e1d0cd0522e37b6bac85065edfe6767fc749c39a0ac257fec51dbff97691
-  data.tar.gz: 12d1d870ed1115cd2044446c66b318f4d6e6c65b1ca3a59493353e5a9d6402a9
+  metadata.gz: 8552bc1992ed59b6f63392207f6a49d12bc9e66ac16cd43b61bb57700f45395e
+  data.tar.gz: 54304e964cff2dc7fafe3ab03c722dfac994011994be96201d700a67e224ec35
 SHA512:
-  metadata.gz: 25198dd08404a6ae41724e8e172ce38f832f19b34efd83761cff86ba033c5952e2d315dad70c75b343cb0c94e216c1d5755a0c53048252a2bd7a1c1a61ac590b
-  data.tar.gz: 49d28d829375c95f39986c6e19ff37d524e06f00ae7c388b743e6cd073a35f9c4717aa47f877bb8802d7c5f12fc1f2dd2d618c12785a6342f8a2164774fe6576
+  metadata.gz: d656b64ce2440c13047ce0802ca968c767cbcfe20eb8b442973e5cc0a63aafb29263081f2ab5c5737260775643193e9fad9eaa08680fe0151b8442efae15128d
+  data.tar.gz: a1a9000773b53140084dd986072d1cbfacda99ba66859cfd5cd82965e163b1aa47184ef64e56cb41ed0a6e0ae2950a96a5f4935e637f073c756de757afb36a53

data/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.21.0](https://github.com/bamr87/zer0-mistakes/compare/v1.20.2...v1.21.0) (2026-06-26)
+
+
+### Features
+
+* **automation:** committee planning + specialized executor agents (Phase 4) ([#226](https://github.com/bamr87/zer0-mistakes/issues/226)) ([1e9016b](https://github.com/bamr87/zer0-mistakes/commit/1e9016b869ff33f26fc60d3ae27e7fcd0216e802))
+* **automation:** issue intake + /issue-implement routing (Phases 2-3) ([#225](https://github.com/bamr87/zer0-mistakes/issues/225)) ([21a7008](https://github.com/bamr87/zer0-mistakes/commit/21a70080b2814827bd390201e1ec76fb2b9a874e))
+* **scripts:** issue adoption in sync-backlog (Phase 1) ([#224](https://github.com/bamr87/zer0-mistakes/issues/224)) ([512068e](https://github.com/bamr87/zer0-mistakes/commit/512068e2556be7fe3a4c7870d9feab0ca52955d8))
+
 ## [1.20.2](https://github.com/bamr87/zer0-mistakes/compare/v1.20.1...v1.20.2) (2026-06-25)
 
 

data/_data/backlog.yml

@@ -44,8 +44,15 @@
 #     summary:    1–2 lines of context
 #     acceptance: List of checkable done-criteria the implement routine verifies
 #     links:      { issue: <#|null>, pr: <#|null>, roadmap: "<version>|null" }
+#                 When `issue:` points at an EXISTING issue, sync ADOPTS it (adds
+#                 a managed block, preserves the author's text, no duplicate)
+#                 instead of creating a new one. At most one task per issue.
 #     created:    YYYY-MM-DD
 #     updated:    YYYY-MM-DD
+#     route:      (optional) executor-lane hint for /issue-implement; resolved via
+#                 _data/routing.yml (defaults to the lane for `area`).
+#     depends_on: (optional) [T-NNN, …] tasks that must land first; consumed by the
+#                 /issue-plan committee for ordering. Advisory.
 #
 # `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

data/_data/roadmap_plan.yml

@@ -0,0 +1,37 @@
+# =============================================================================
+# Roadmap plan — ORDER-ONLY sequencing artifact
+# =============================================================================
+# Produced by the /issue-plan committee (.github/prompts/issue-plan.prompt.md).
+# Validated + mirrored by scripts/sync-plan.rb.
+#
+# This file sequences OPEN backlog tasks into batches. It is ADVISORY input to
+# the human-dispatched /issue-implement ordering — it does not dispatch anything.
+#
+# HARD INVARIANT (enforced by `sync-plan.rb --check`): order only. A batch may
+# carry ONLY `id`, `goal`, `tasks` (bare T-NNN ids that exist + are open),
+# `depends_on` (other batch ids; the DAG must be acyclic), and `test_framework`.
+# It may NEVER carry risk / priority / area / status / effort / acceptance —
+# those are DERIVED at read-time from `_data/backlog.yml` (the single source of
+# truth), exactly as /backlog-implement already does. Two sources of truth drift.
+#
+# Example batch shape:
+#   batches:
+#     - id: B-1
+#       goal: "Unblock remote-theme consumers"
+#       tasks: [T-027, T-031]
+#       depends_on: []
+#       test_framework: "Playwright smoke for the 404 path + a remote-theme build matrix job"
+#     - id: B-2
+#       goal: "Theme chrome a11y pass"
+#       tasks: [T-033]
+#       depends_on: [B-1]
+#       test_framework: "axe-core checks + before/after visual evidence per the visual-evidence skill"
+# =============================================================================
+
+meta:
+  title: "zer0-mistakes Roadmap Plan"
+  updated: 2026-06-25
+  generated_by: "/issue-plan"
+
+# Populated by the committee. Empty is valid (nothing sequenced yet).
+batches: []

data/_data/routing.yml

@@ -0,0 +1,73 @@
+# =============================================================================
+# Issue routing — area:* (+ optional path globs) → executor lane
+# =============================================================================
+# Used by /issue-implement to pick the specialized executor for a task/issue.
+#
+# Resolution order:
+#   1. explicit task.route -> that lane (override)
+#   2. first `rules` entry whose `area` matches the task's area AND (if it lists
+#      `paths`) a path glob matches a file the work is expected to touch
+#   3. `default` lane
+#
+# A "lane" pairs a specialized .claude/agents/<agent>.md executor with the
+# file-scoped instructions + skills it must load. In v1 (until the cloud-routine
+# substrate spike proves prompt->subagent dispatch), /issue-implement loads the
+# lane's `instructions` + `skills` INLINE and the named `agent` is advisory; once
+# the spike passes it delegates to the agent. Either way the lane is the same.
+#
+# NOTE: this file is DATA. It never grants autonomy — risk/auto-merge eligibility
+# is derived from the backlog task per the autonomy policy in
+# docs/systems/continuous-evolution.md, not from the lane.
+# =============================================================================
+
+default: code-fixer
+
+lanes:
+  content:
+    agent: content-reviewer
+    instructions: [content-review.instructions.md, documentation.instructions.md]
+    skills: [content-review, validate-build]
+    done: "content builds; deterministic + AI content review clean"
+  theme-ui:
+    agent: theme-ui
+    instructions: [layouts.instructions.md, includes.instructions.md, sass.instructions.md, visual-evidence.instructions.md]
+    skills: [change-workflow, visual-evidence, validate-build]
+    done: "jekyll build green; regression spec + before/after evidence committed"
+  code-fixer:
+    agent: code-fixer
+    instructions: [includes.instructions.md, layouts.instructions.md, scripts.instructions.md]
+    skills: [change-workflow, validate-build]
+    done: "targeted tests green; jekyll build green if templates touched"
+  infra-scripts:
+    agent: infra-scripts
+    instructions: [scripts.instructions.md]
+    skills: [change-workflow, validate-build]
+    done: "scripts run; shellcheck/tests green; no CODEOWNERS-owned path touched"
+  test-author:
+    agent: test-author
+    instructions: [testing.instructions.md, visual-evidence.instructions.md]
+    skills: [validate-build]
+    done: "new test fails before the fix and passes after; suite green"
+  a11y:
+    agent: a11y-fixer
+    instructions: [includes.instructions.md, layouts.instructions.md, sass.instructions.md, visual-evidence.instructions.md]
+    skills: [change-workflow, visual-evidence, validate-build]
+    done: "axe/a11y checks pass; regression spec + evidence committed"
+  deps:
+    agent: deps-bumper
+    instructions: []
+    skills: [change-workflow, validate-build]
+    done: "lockfiles consistent; build + tests green"
+
+# First match wins. `feat` appears twice on purpose: a UI-touching feat routes to
+# theme-ui, anything else falls through to the default code-fixer.
+rules:
+  - { area: docs,  lane: content }
+  - { area: a11y,  lane: a11y }
+  - { area: tests, lane: test-author }
+  - { area: infra, lane: infra-scripts }
+  - { area: deps,  lane: deps }
+  - { area: feat,  paths: ["_layouts/**", "_includes/**", "_sass/**", "assets/**"], lane: theme-ui }
+  - { area: feat,  lane: code-fixer }
+  - { area: perf,  lane: code-fixer }
+  - { area: lint,  lane: code-fixer }

data/scripts/sync-backlog.rb

@@ -89,6 +89,7 @@ def validate(data)
   return ['Missing or empty `tasks:` list.'] unless tasks.is_a?(Array) && !tasks.empty?
 
   seen_ids = {}
+  seen_links = {}
   tasks.each_with_index do |task, i|
     where = "tasks[#{i}]"
     unless task.is_a?(Hash)
@@ -114,6 +115,30 @@ def validate(data)
     unless task['acceptance'].is_a?(Array) && !task['acceptance'].empty?
       errors << "#{where}: `acceptance` must be a non-empty list."
     end
+
+    # Adoption guard: an existing GitHub issue may be claimed by at most one task,
+    # so two tasks can never fight over (or duplicate) the same issue.
+    lnk = task.dig('links', 'issue')
+    if lnk
+      unless lnk.is_a?(Integer) || lnk.to_s =~ /\A\d+\z/
+        errors << "#{where}: `links.issue` must be an issue number (got #{lnk.inspect})."
+      end
+      key = lnk.to_s
+      if seen_links[key]
+        errors << "#{where}: `links.issue` ##{key} already claimed by #{seen_links[key]}."
+      else
+        seen_links[key] = (id || where)
+      end
+    end
+    # Optional routing/dependency metadata (consumed by /issue-implement + /issue-plan).
+    if task.key?('route') && !task['route'].is_a?(String)
+      errors << "#{where}: `route` must be a string."
+    end
+    if task.key?('depends_on') &&
+       !(task['depends_on'].is_a?(Array) &&
+         task['depends_on'].all? { |d| d.is_a?(String) && d =~ /\AT-\d{3,}\z/ })
+      errors << "#{where}: `depends_on` must be a list of T-NNN ids."
+    end
   end
   errors
 end
@@ -133,6 +158,52 @@ def marker(id)
   "<!-- backlog-id: #{id} -->"
 end
 
+# Delimiters around the sync-owned section of an ADOPTED human issue. Text ABOVE
+# the start delimiter (the author's original report) is never touched; only this
+# block is upserted on each sync, so adoption is non-destructive.
+MANAGED_START = '<!-- backlog-managed:start -->'
+MANAGED_END   = '<!-- backlog-managed:end -->'
+
+def render_managed_block(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(' · ')
+
+  <<~BLOCK.strip
+    #{MANAGED_START}
+    #{marker(task['id'])}
+    > Tracked from [`_data/backlog.yml`](../blob/main/_data/backlog.yml) by `scripts/sync-backlog.rb`.
+    > The report above is the author's; this block is auto-managed — edit the backlog, not here.
+
+    #{meta_row}#{roadmap ? " · **Roadmap:** v#{roadmap}" : ''}
+
+    ## Acceptance criteria
+
+    #{accept}
+
+    Picked up by the IMPLEMENT routine; see [`docs/systems/continuous-evolution.md`](../blob/main/docs/systems/continuous-evolution.md).
+    #{MANAGED_END}
+  BLOCK
+end
+
+# Upsert the managed block into a (human-authored) issue body, preserving the
+# author's text. Idempotent: replaces an existing block, else appends one.
+def upsert_managed_block(body, task)
+  body  = body.to_s
+  block = render_managed_block(task)
+  if body.include?(MANAGED_START) && body.include?(MANAGED_END)
+    body.sub(/#{Regexp.escape(MANAGED_START)}.*#{Regexp.escape(MANAGED_END)}/m, block)
+  else
+    "#{body.rstrip}\n\n#{block}\n"
+  end
+end
+
 def render_body(task)
   accept = (task['acceptance'] || []).map { |a| "- [ ] #{a}" }.join("\n")
   roadmap = task.dig('links', 'roadmap')
@@ -202,26 +273,52 @@ def ensure_labels(gh)
   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)
+# Returns [index, link_state]:
+#   index      — backlog id -> {number,state,labels,body,marker_id} for every
+#                marker-bearing agent-ready issue (the already-managed ones).
+#   link_state — issue number -> same record, for each issue referenced by a task
+#                `links.issue`. A human issue may carry neither the agent-ready
+#                label nor a marker yet, so it is fetched by number for adoption +
+#                provenance checks (is it already claimed by a foreign marker?).
+def existing_issues(gh, link_numbers = [])
+  index = {}
+  link_state = {}
+  to_rec = lambda do |issue|
+    body = issue['body'].to_s
+    rec = {
+      'number'    => issue['number'],
+      'state'     => issue['state'].to_s.downcase,
+      'labels'    => (issue['labels'] || []).map { |l| l['name'] },
+      'body'      => body,
+      'marker_id' => body[/<!-- backlog-id: (T-\d+) -->/, 1]
+    }
+    index[rec['marker_id']] = rec if rec['marker_id']
+    rec
+  end
+
   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+) -->/
+  begin
+    JSON.parse(raw).each { |issue| to_rec.call(issue) }
+  rescue JSON::ParserError
+    # leave index empty; adoption/create still work off link_state
+  end
 
-    index[Regexp.last_match(1)] = {
-      'number' => issue['number'],
-      'state'  => issue['state'].to_s.downcase,
-      'labels' => (issue['labels'] || []).map { |l| l['name'] }
-    }
+  link_numbers.compact.map(&:to_i).uniq.each do |n|
+    raw1 = gh.read(['issue', 'view', n.to_s, '--json', 'number,body,state,labels'], default: '')
+    next if raw1.strip.empty?
+
+    begin
+      link_state[n] = to_rec.call(JSON.parse(raw1))
+    rescue JSON::ParserError
+      next
+    end
   end
-  index
-rescue JSON::ParserError
-  {}
+
+  [index, link_state]
 end
 
 # ---------------------------------------------------------------------------
@@ -241,29 +338,55 @@ 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)
+  tasks = data['tasks'] || []
+  link_numbers = tasks.map { |t| t.dig('links', 'issue') }.compact
+  index, link_state = existing_issues(gh, link_numbers)
+  created = adopted = updated = closed = 0
+
+  tasks.each do |task|
+    id        = task['id']
+    title     = task['title']
     want_open = OPEN_STATUSES.include?(task['status'])
-    issue = index[id]
+    lnk       = task.dig('links', 'issue')
+    issue     = index[id] # already marker-tracked?
+
+    # Adoption: task points at an existing issue not yet marker-tracked. Adopt it
+    # (inject the managed block) instead of creating a duplicate — unless the
+    # issue already carries a DIFFERENT marker (foreign provenance → refuse).
+    if issue.nil? && lnk
+      ls = link_state[lnk.to_i]
+      if ls.nil?
+        warn "task #{id}: links.issue ##{lnk} not found — creating a new issue instead."
+      elsif ls['marker_id'] && ls['marker_id'] != id
+        warn "task #{id}: refusing to adopt ##{lnk} — already marked #{ls['marker_id']} (foreign). Skipping."
+        next
+      else
+        issue = ls.merge('adopt' => true)
+      end
+    end
 
     if issue.nil?
       next unless want_open # never create an issue for an already-done task
 
-      args = ['issue', 'create', '--title', title, '--body', body]
+      args = ['issue', 'create', '--title', title, '--body', render_body(task)]
       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 lnk
+      # Human-authored (adopted) issue: NEVER overwrite its title/body — only
+      # upsert the managed block (preserving the author's report) + labels.
+      gh.write(['issue', 'edit', number, '--body', upsert_managed_block(issue['body'], task)] +
+               label_args(managed_labels(task), issue['labels']))
+      issue['adopt'] ? (adopted += 1) : (updated += 1)
+    else
+      # Bot-created issue: fully sync-owned title + body.
+      gh.write(['issue', 'edit', number, '--title', title, '--body', render_body(task)] +
+               label_args(managed_labels(task), issue['labels']))
+      updated += 1
+    end
 
     if want_open && issue['state'] != 'open'
       gh.write(['issue', 'reopen', number])
@@ -273,7 +396,7 @@ def sync(data, gh)
     end
   end
 
-  puts "Backlog sync complete: #{created} created, #{updated} updated, #{closed} closed."
+  puts "Backlog sync complete: #{created} created, #{adopted} adopted, #{updated} updated, #{closed} closed."
   0
 end
 

data/scripts/sync-plan.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# sync-plan.rb
+# =============================================================================
+#
+# Validates (and optionally mirrors) `_data/roadmap_plan.yml` — the ORDER-ONLY
+# plan artifact produced by the /issue-plan committee. The plan sequences open
+# backlog tasks into batches; it must NEVER re-encode anything the backlog owns
+# (risk / priority / area / status / effort), which would create a second source
+# of truth that drifts.
+#
+#   ruby scripts/sync-plan.rb --check    # validate the plan vs the backlog (CI/PR gate; stdlib only)
+#   ruby scripts/sync-plan.rb --dry-run  # print the intended pinned-issue upsert
+#   ruby scripts/sync-plan.rb            # upsert one pinned tracking issue via `gh`
+#
+# --check asserts:
+#   * every batch task id exists in _data/backlog.yml and is OPEN (not done),
+#   * batch `depends_on` references existing batch ids and the batch DAG is acyclic,
+#   * no plan entry carries a backlog-owned field (order-only invariant).
+# =============================================================================
+
+require 'yaml'
+require 'date'
+require 'json'
+require 'optparse'
+require 'open3'
+
+ROOT      = File.expand_path('..', __dir__)
+PLAN_FILE = File.join(ROOT, '_data', 'roadmap_plan.yml')
+BACKLOG   = File.join(ROOT, '_data', 'backlog.yml')
+
+PIN_MARKER         = '<!-- roadmap-plan:pinned -->'
+BACKLOG_OWNED      = %w[risk priority area status effort source acceptance title].freeze
+OPEN_TASK_STATUS   = %w[open in-progress blocked].freeze
+
+def load_yaml(path)
+  YAML.load_file(path, permitted_classes: [Date, Time])
+rescue ArgumentError
+  YAML.safe_load(File.read(path, encoding: 'UTF-8'), permitted_classes: [Date, Time], aliases: false)
+end
+
+def backlog_status
+  tasks = (load_yaml(BACKLOG)['tasks'] || [])
+  tasks.each_with_object({}) { |t, h| h[t['id']] = t['status'] }
+end
+
+def validate(plan, statuses)
+  errors = []
+  unless plan.is_a?(Hash) && plan['batches'].is_a?(Array)
+    return ['plan must have a `batches:` list.']
+  end
+
+  batch_ids = plan['batches'].map { |b| b['id'] }.compact
+  seen = {}
+  batch_ids.each { |bid| seen[bid] ? (errors << "duplicate batch id #{bid}.") : (seen[bid] = true) }
+
+  plan['batches'].each_with_index do |batch, i|
+    where = batch['id'] ? "batch #{batch['id']}" : "batches[#{i}]"
+    errors << "#{where}: missing `id`." if batch['id'].to_s.empty?
+
+    # Order-only invariant: a batch (or its task entries) may not carry a field
+    # the backlog owns. Tasks must be bare id strings.
+    (BACKLOG_OWNED & batch.keys).each { |k| errors << "#{where}: must not carry backlog-owned field `#{k}`." }
+    Array(batch['tasks']).each do |t|
+      unless t.is_a?(String) && t =~ /\AT-\d{3,}\z/
+        errors << "#{where}: task entries must be bare T-NNN ids (got #{t.inspect})."
+        next
+      end
+      if !statuses.key?(t)
+        errors << "#{where}: task #{t} is not in the backlog."
+      elsif !OPEN_TASK_STATUS.include?(statuses[t])
+        errors << "#{where}: task #{t} is #{statuses[t]} (only open tasks may be planned)."
+      end
+    end
+
+    Array(batch['depends_on']).each do |dep|
+      errors << "#{where}: depends_on references unknown batch #{dep}." unless seen[dep]
+    end
+  end
+
+  errors.concat(cycle_errors(plan['batches']))
+  errors
+end
+
+# Kahn's algorithm over the batch DAG; any leftover nodes => a cycle.
+def cycle_errors(batches)
+  deps = {}
+  batches.each { |b| deps[b['id']] = Array(b['depends_on']).dup }
+  indeg = Hash.new(0)
+  deps.each { |_n, ds| ds.each { |d| indeg[d] += 1 if deps.key?(d) } }
+  # Edge dep -> node (dep must precede node); compute order by repeatedly removing
+  # nodes whose deps are all satisfied.
+  remaining = deps.keys
+  progress = true
+  while progress
+    progress = false
+    ready = remaining.select { |n| deps[n].all? { |d| !remaining.include?(d) } }
+    unless ready.empty?
+      remaining -= ready
+      progress = true
+    end
+  end
+  remaining.empty? ? [] : ["batch dependency cycle among: #{remaining.sort.join(', ')}."]
+end
+
+def pinned_body(plan)
+  lines = ["#{PIN_MARKER}", '> Auto-managed by `scripts/sync-plan.rb` from `_data/roadmap_plan.yml`.',
+           '> Order only — risk/priority/area come from `_data/backlog.yml`.', '']
+  plan['batches'].each do |b|
+    lines << "### #{b['id']} — #{b['goal']}"
+    lines << "Tasks: #{Array(b['tasks']).join(', ')}"
+    lines << "Depends on: #{Array(b['depends_on']).join(', ')}" unless Array(b['depends_on']).empty?
+    lines << "Test framework: #{b['test_framework']}" if b['test_framework']
+    lines << ''
+  end
+  lines.join("\n").strip
+end
+
+def upsert_pinned(plan, dry_run:)
+  title = '📋 Roadmap plan (auto-managed)'
+  body  = pinned_body(plan)
+  found = `gh issue list --search #{PIN_MARKER.inspect}\\ in:body --state open --json number --jq '.[0].number' 2>/dev/null`.strip
+  args =
+    if found.empty?
+      ['issue', 'create', '--title', title, '--body', body, '--label', 'agent-hold']
+    else
+      ['issue', 'edit', found, '--title', title, '--body', body]
+    end
+  if dry_run
+    puts "DRY-RUN gh #{args.join(' ')}"
+    return
+  end
+  _o, err, st = Open3.capture3('gh', *args)
+  warn "gh failed: #{err}" unless st.success?
+end
+
+def main
+  mode = :sync
+  OptionParser.new do |o|
+    o.on('--check') { mode = :check }
+    o.on('--dry-run') { mode = :dry_run }
+  end.parse!
+
+  return 0 unless File.exist?(PLAN_FILE) # no plan yet => nothing to validate
+
+  plan = load_yaml(PLAN_FILE)
+  errors = validate(plan, backlog_status)
+  unless errors.empty?
+    warn '✗ _data/roadmap_plan.yml failed validation:'
+    errors.each { |e| warn "  - #{e}" }
+    return 1
+  end
+
+  if mode == :check
+    puts "✓ _data/roadmap_plan.yml is valid (#{plan['batches'].size} batches)."
+    return 0
+  end
+  upsert_pinned(plan, dry_run: mode == :dry_run)
+  0
+end
+
+exit main if $PROGRAM_NAME == __FILE__

data/scripts/sync-plan.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# =============================================================================
+# sync-plan.sh
+# =============================================================================
+#
+# Thin wrapper around scripts/sync-plan.rb.
+#
+# Validates (and optionally mirrors) `_data/roadmap_plan.yml` — the order-only
+# plan artifact produced by the /issue-plan committee — against the backlog.
+#
+# Usage:
+#   ./scripts/sync-plan.sh             # upsert the pinned tracking issue via gh
+#   ./scripts/sync-plan.sh --check     # validate plan vs backlog (CI/PR gate)
+#   ./scripts/sync-plan.sh --dry-run   # print the intended gh call only
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec ruby "${SCRIPT_DIR}/sync-plan.rb" "$@"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.20.2
+  version: 1.21.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -99,6 +99,8 @@ files:
 - _data/prerequisites.yml
 - _data/prompts.yml
 - _data/roadmap.yml
+- _data/roadmap_plan.yml
+- _data/routing.yml
 - _data/statistics_config.yml
 - _data/theme-manifest.yml
 - _data/theme_backgrounds.yml
@@ -491,6 +493,8 @@ files:
 - scripts/setup.sh
 - scripts/sync-backlog.rb
 - scripts/sync-backlog.sh
+- scripts/sync-plan.rb
+- scripts/sync-plan.sh
 - scripts/test-auto-version.sh
 - scripts/test-mermaid.sh
 - scripts/test-notebook-conversion.sh