jekyll-theme-zer0 1.20.2 → 1.22.0

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.22.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-06-29 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
@@ -374,6 +376,7 @@ files:
 - scripts/analyze-commits.sh
 - scripts/bin/audit-consumer
 - scripts/bin/build
+- scripts/bin/giscus-discussions
 - scripts/bin/install
 - scripts/bin/manifest
 - scripts/bin/release
@@ -491,6 +494,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