commenter 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1609bb9eed80e408daebc9c67cda2c657e8484186acce89b823e6b411a5f9ea5
-  data.tar.gz: 46316674e2c639b9256390385d2cb3c59ed8946b604b44fbb0be28728475cd38
+  metadata.gz: 077fd6e045907b803d3f6b33d305bab0a4544b37ede3855fb26af1974f48385a
+  data.tar.gz: ffe50dadee86e040ce1b0b5fbb367f5e5233f4bd668248e9f473c2f9bfbccfb3
 SHA512:
-  metadata.gz: 887aa19ab8ca3559fd20caf3e19a9941b631c677faeda86553597671883fc8dbae8c1e1f6d83bd0014e036774743addc16bc538b7404f6939be6636e1d623704
-  data.tar.gz: 3b850d0872f2f572b599d0bf7a70a977e1e5e7e797f5fb3447905c09cc7578cff18d99de6b32ae3b539758b7319b07590fdfd9d5249f74024ffdcd842d48d09d
+  metadata.gz: f3a1e36e43d5dc1d16717afab89546c3c8151c38c56c8b2f8cdbf5885a0cb5d38a34f6a6a1869892bc07a1ff0efe4f4d229a4137241565d74d4e4920555eba4b
+  data.tar.gz: d368ce137f669d56ec8c72da5c3a106c7acc95e19c8daa0c3371e09cc91c5af79e6d0af0cfd4498ac466aef96c26377c5020647b8132a59fce453574a303217a

data/.rubocop.yml

@@ -16,3 +16,7 @@ Metrics/ModuleLength:
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
+
+Metrics/ClassLength:
+  Exclude:
+    - "lib/commenter/cli.rb"

data/CONTEXT.md

@@ -0,0 +1,33 @@
+# CONTEXT.md — Domain Glossary
+
+The domain language of the commenter gem. Used to name modules and commands;
+keep this current when concepts sharpen.
+
+- **Comment Sheet** — one ballot submission as a whole: metadata (document,
+  stage, date, project, titles) plus its comments. `CommentSheet`.
+- **Comment** — a single remark on a document: identity (id, member body),
+  locality (clause, element, line), type, the remark text, the proposed
+  change, and the disposition (`observations`).
+- **Member Body** — the national body or committee that submitted the comment
+  (`DE`, `US`, `CS` for the ISO/CS secretariat, `**` for ISO itself). A
+  secretariat receives one sheet per member body per ballot.
+- **Ballot** — the set of all comment sheets for one ballot round. Merging
+  member sheets into one is collation; `Ballot`.
+- **Disposition** — the resolution of a comment: accepted, accept with
+  modifications, noted, rejected, or still open. `DispositionStatus` is the
+  single matcher for both free-text observations and OSD's structured
+  `resolution_status`.
+- **Stage** — the ballot stage of the document (WD, CD, DIS, FDIS, PRF, PUB).
+  The same comment ID at different stages is a different comment.
+- **Redline** — a DOCX with tracked changes (`w:ins`/`w:del`/moves), typically
+  from ISO/CS editors; also carries reviewer remark threads.
+- **OSD** — ISO Online Standards Development; its XLSX comment exports come
+  in resolved and unresolved variants.
+- **Stage Comparison** — how the comment set evolved between two ballots
+  (new, withdrawn, repeated, revised; resolved = disposition recorded).
+  `BallotDiff`.
+- **GitHub Sync** — reconciliation of the comment YAML with GitHub issues
+  (YAML as source of truth): create missing, refresh content per conflict
+  policy, close dispositioned issues. `GitHubSync`.
+- **Unique ID** — stage-aware identity of a comment's GitHub issue
+  (`[DIS] GB-001` by default), used for duplicate detection.

data/README.adoc

@@ -124,12 +124,16 @@ Options:
 ==== Metadata (extraction limitation)
 
 WARNING: Due to a limitation in the underlying `docx` gem, metadata fields
-(Date, Document, Project) from the DOCX header cannot be automatically
-extracted. This is because the required functionality is not yet merged (see
-https://github.com/ruby-docx/docx/pull/73[docx gem PR #73]).
+(Date, Document, Project) cannot yet be automatically extracted from the DOCX
+header during import (see https://github.com/ruby-docx/docx/pull/73[docx gem
+PR #73]). Redline imports take them from the `--document` / `--stage` options;
+for template imports, populate the YAML fields manually.
 
-The generated YAML will have empty metadata fields that you can manually
-populate:
+The reverse direction works: `commenter fill` writes the sheet's
+`date`, `document`, and `project` values into the Date/Document/Project labels
+of the template's page header, so the filled comment sheet is complete.
+
+For template imports, populate the YAML metadata manually:
 
 [source,yaml]
 ----
@@ -142,9 +146,6 @@ project: ""        # Manually add: e.g., "Project name"
 comments:
 ----
 
-Alternatively, you can provide metadata during import using CLI options (planned
-for future release).
-
 
 ==== Example YAML output
 
@@ -189,11 +190,70 @@ comments:
     observations:
 ----
 
+=== Merging comment sheets (ballot collation)
+
+A secretariat receives one comment file per member body per ballot — mixed
+DOCX templates, OSD XLSX exports, and late redlines that arrive by email.
+`commenter merge` collates them into a single ballot sheet:
+
+[source,shell]
+----
+commenter merge de.yaml us.yaml jp.yaml cs-redline.yaml -o ballot.yaml
+----
+
+Metadata (document, stage, date) is taken from the first sheet that provides
+each field. Comments keep their input order. Identical duplicates of the same
+comment ID are deduplicated silently; the same ID with differing content
+raises an error listing the conflicting IDs — collation stops loudly rather
+than silently dropping a member's comment.
+
+=== Ballot statistics (disposition reports)
+
+Every ballot report needs disposition counts — by member body and overall.
+The data is already in the YAML, so `commenter stats` produces the table:
+
+[source,shell]
+----
+commenter stats ballot.yaml
+----
+
+[source,markdown]
+....
+| Body | Total | Accepted | AWM | Noted | Rejected | TODO | Open | Undecided |
+|------|-------|----------|-----|-------|----------|------|------|-----------|
+| DE   | 12    | 5        | 3   | 2     | 1        | 0    | 0    | 1         |
+| US   | 9     | 4        | 1   | 2     | 1        | 0    | 1    | 0         |
+| **Total** | **21** | **9** | **4** | **4** | **2** | **0** | **1** | **1** |
+
+Comment types: technical 13 · general 5 · editorial 3
+....
+
+A comment's disposition is read from its `observations` text, falling back to
+the OSD `resolution_status` field, then to the GitHub issue state (a still-open
+issue counts as *open*; no disposition at all counts as *undecided*). Use
+`--format yaml` for machine-readable output, and `-o report.md` to write to a
+file — the Markdown pastes directly into a GitHub issue or WG minutes.
+
+=== Comparing ballots between stages
+
+The same comment ID (`DE-001`) recurs at every ballot stage; comparing two
+ballot sheets shows how the set evolved between CD and DIS:
+
+[source,shell]
+----
+commenter diff cd-ballot.yaml dis-ballot.yaml
+----
+
+Comments are matched by ID and classified as new, withdrawn, repeated
+(unchanged text), or revised; a comment whose later version carries a
+disposition counts as resolved. Markdown (default) or `--format yaml`.
+
 === Filling DOCX templates from YAML
 
 This gem contains a command-line utility to fill a DOCX template with comments
 from a YAML file. It generates a filled comment sheet that can be used for
-review and resolution tracking.
+review and resolution tracking. The sheet's `date`, `document`, and `project`
+metadata are written into the template's page header.
 
 The base template is the ISO comment sheet template located at
 `data/iso_comment_template_2012-03.docx`. You can also provide a custom
@@ -418,6 +478,35 @@ The `unique_id` is available as a variable in title and body templates:
 
 This renders to: `[DIS] GB-001: Clause 5.1 summary (ISO/DIS 2533)`
 
+==== Synchronizing with GitHub issues
+
+`github-create` is one-shot: it creates missing issues and skips existing
+ones. `github-sync` keeps the YAML and the issues in step, treating the YAML
+as the source of truth:
+
+[source,shell]
+----
+commenter github-sync --config github_config.yaml comments.yaml
+----
+
+For each comment it creates a missing issue, refreshes issue content from
+the YAML, and reconciles issue state. Two policies govern the parts that
+can collide:
+
+`--conflict yaml` (default):: Re-render the issue title and body from the
+YAML when they differ (YAML wins).
+`--conflict github`:: Leave differing issue content untouched (edits made
+on GitHub win).
+`--conflict skip`:: Take no action on differing content; the result is
+reported as a conflict.
+
+By default an open issue whose comment has a recorded disposition
+(`observations`) is closed — that is what keeps the
+`github-retrieve` round-trip working, since observations are retrieved from
+closed issues. Disable with `--no-close-on-disposition`.
+
+The milestone is resolved once per run and reused for every issue.
+
 ==== Retrieving observations from GitHub issues
 
 ===== Basic usage
@@ -605,10 +694,10 @@ recognized and applied to the observations column:
 |===
 | Status Pattern | Intended Color | Hex Code | Example
 
+| `awm\|accept(ed)? with (modifications\|changes)` | Olive Green | #C4D79B | "Accepted with modifications"
 | `accept(ed)?` | Green | #92D050 | "Accepted"
-| `awm\|accept with modifications` | Olive Green | #C4D79B | "Accept with modifications"
 | `noted` | Blue | #8DB4E2 | "Noted"
-| `reject(ed)?` | Pink | #FF99CC | "Rejected"
+| `reject(ed)?\|not accepted` | Pink | #FF99CC | "Rejected"
 | `todo` | Diagonal stripes | #D9D9D9 | "TODO: Review"
 
 |===

data/commenter.gemspec

@@ -34,6 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "docx", "~> 0.8"
   spec.add_dependency "dotenv", "~> 2.8"
   spec.add_dependency "liquid", "~> 5.0"
+  spec.add_dependency "lutaml-model", "~> 0.8"
   spec.add_dependency "octokit", "~> 6.0"
   spec.add_dependency "roo", ">= 2.10"
   spec.add_dependency "thor", "~> 1.0"

data/lib/commenter/ballot.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Merges member-body comment sheets into a single ballot sheet — the
+  # collation step secretariats otherwise do by hand (ISO's own Comment
+  # Collation Tool fails on non-conforming files).
+  #
+  # Policy: sheet metadata is first-non-nil across the given sheets (the
+  # output version comes from the first sheet); comments keep their input
+  # order. Identical duplicate IDs are deduplicated silently; the same ID
+  # with differing content raises.
+  class Ballot
+    def initialize(sheets)
+      @sheets = sheets
+    end
+
+    def merge
+      CommentSheet.new(
+        version: first_sheet&.version || "2012-03",
+        date: first_value(:date),
+        document: first_value(:document),
+        project: first_value(:project),
+        stage: first_value(:stage),
+        title_en: first_value(:title_en),
+        title_fr: first_value(:title_fr),
+        comments: deduplicate(@sheets.flat_map(&:comments))
+      )
+    end
+
+    private
+
+    def first_sheet
+      @sheets.first
+    end
+
+    def first_value(attribute)
+      @sheets.lazy.map { |sheet| sheet.public_send(attribute) }.find { |value| !value.nil? }
+    end
+
+    def deduplicate(comments)
+      seen = {}
+      conflicts = []
+      kept = comments.reject do |comment|
+        key = comment.id.to_s
+        next false if key.empty?
+
+        existing = seen[key]
+        if existing.nil?
+          seen[key] = comment
+          false
+        elsif identical?(existing, comment)
+          true
+        else
+          conflicts << key
+          false
+        end
+      end
+      return kept if conflicts.empty?
+
+      raise Commenter::Error, "Duplicate comment IDs with differing content: #{conflicts.uniq.sort.join(", ")}"
+    end
+
+    def identical?(one, another)
+      one.comments == another.comments && one.proposed_change == another.proposed_change
+    end
+  end
+end

data/lib/commenter/ballot_diff.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Stage-to-stage comparison of two ballots: how the comment set evolved
+  # between e.g. CD and DIS — new comments, withdrawn comments, repeated
+  # unchanged comments, and revised ones. Comments are matched by ID (member
+  # body + number), which repeats across stages.
+  module BallotDiff
+    module_function
+
+    def diff(before_sheet, after_sheet)
+      before_comments = indexed(before_sheet)
+      after_comments = indexed(after_sheet)
+
+      result = { new: [], withdrawn: [], repeated: [], revised: [], resolved: [] }
+      after_comments.each do |id, after|
+        before = before_comments[id]
+        if before.nil?
+          result[:new] << id
+        elsif identical?(before, after)
+          result[:repeated] << id
+        else
+          result[:revised] << id
+        end
+        result[:resolved] << id if dispositioned?(after)
+      end
+      before_comments.each_key { |id| result[:withdrawn] << id unless after_comments.key?(id) }
+
+      result.each_value(&:sort!)
+      result
+    end
+
+    def to_markdown(before_sheet, after_sheet)
+      data = diff(before_sheet, after_sheet)
+      lines = []
+      lines << "| Category | Count | Comments |"
+      lines << "|----------|-------|----------|"
+      data.each do |category, ids|
+        label = category.to_s.tr("_", " ").capitalize
+        listed = ids.length <= 10 ? ids.join(", ") : "#{ids.first(10).join(", ")} …"
+        lines << "| #{label} | #{ids.length} | #{listed} |"
+      end
+      lines << ""
+      lines << "Resolved (disposition recorded in the later stage): #{data[:resolved].length}"
+      lines.join("\n")
+    end
+
+    def indexed(sheet)
+      sheet.comments.each_with_object({}) do |comment, index|
+        key = comment.id.to_s
+        index[key] = comment unless key.empty?
+      end
+    end
+
+    def identical?(before, after)
+      before.comments == after.comments && before.proposed_change == after.proposed_change
+    end
+
+    def dispositioned?(comment)
+      observation = comment.observations.to_s.strip
+      !observation.empty? || DispositionStatus.match(comment.resolution_status)
+    end
+  end
+end

data/lib/commenter/ballot_report.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Commenter
+  # Disposition statistics over a comment sheet: the counts ballot reports
+  # need — comments per member body by disposition, and per comment type.
+  module BallotReport
+    module_function
+
+    # status bucket for one comment: matched observation text, else matched
+    # OSD resolution_status, else open when a GitHub issue is still open,
+    # else undecided.
+    def status_for(comment)
+      DispositionStatus.match(comment.observations) ||
+        DispositionStatus.match(comment.resolution_status) ||
+        (comment.github&.status == "open" ? :open : nil) ||
+        (comment.observations.to_s.strip.empty? && comment.resolution_status.to_s.strip.empty? ? :undecided : nil)
+    end
+
+    def counts(comment_sheet)
+      bodies = Hash.new { |hash, body| hash[body] = bucket_hash }
+      types = Hash.new(0)
+      comment_sheet.comments.each do |comment|
+        body = comment.body.to_s.strip.empty? ? "(unknown)" : comment.body
+        bodies[body][:total] += 1
+        status = status_for(comment)
+        bodies[body][status] += 1 if status
+        types[comment.type.to_s.strip.empty? ? "(untyped)" : comment.type] += 1
+      end
+      { total: bodies.values.sum { |bucket| bucket[:total] }, bodies: bodies, types: types }
+    end
+
+    def to_markdown(comment_sheet)
+      data = counts(comment_sheet)
+      sorted_bodies = data[:bodies].sort_by { |body, _| body }
+
+      lines = []
+      lines << "| Body | Total | Accepted | AWM | Noted | Rejected | TODO | Open | Undecided |"
+      lines << "|------|-------|----------|-----|-------|----------|------|------|-----------|"
+      sorted_bodies.each do |body, bucket|
+        lines << "| #{body} | #{bucket[:total]} | #{bucket[:accepted]} | #{bucket[:accept_with_modifications]} | " \
+                 "#{bucket[:noted]} | #{bucket[:rejected]} | #{bucket[:todo]} | #{bucket[:open]} | #{bucket[:undecided]} |"
+      end
+      totals = data[:bodies].values.reduce(bucket_hash) { |sum, bucket| merge_bucket(sum, bucket) }
+      lines << "| **Total** | **#{totals[:total]}** | **#{totals[:accepted]}** | " \
+               "**#{totals[:accept_with_modifications]}** | **#{totals[:noted]}** | " \
+               "**#{totals[:rejected]}** | **#{totals[:todo]}** | **#{totals[:open]}** | **#{totals[:undecided]}** |"
+      lines << ""
+      lines << "Comment types: #{data[:types].sort_by { |type, _| type }.map { |type, count| "#{type} #{count}" }.join(" · ")}"
+      lines.join("\n")
+    end
+
+    def bucket_hash
+      { total: 0, accepted: 0, accept_with_modifications: 0, noted: 0, rejected: 0, todo: 0, open: 0, undecided: 0 }
+    end
+
+    def merge_bucket(sum, bucket)
+      sum.merge(bucket) { |_key, accumulated, addition| accumulated + addition }
+    end
+  end
+end

data/lib/commenter/cli.rb

@@ -21,33 +21,71 @@ module Commenter
     option :document, type: :string, desc: "Redline: document identifier (e.g. ISO 2533:2026)"
     option :stage, type: :string, desc: "Redline: approval stage (e.g. DIS)"
     def import(input_file)
-      output_yaml = options[:output]
-      schema_dir = options[:schema_dir]
-
-      # Ensure schema directory exists
-      FileUtils.mkdir_p(schema_dir) unless Dir.exist?(schema_dir)
-
       # Parse the input file
-      parser = Parser.new
-      comment_sheet = parser.parse(input_file, options)
+      comment_sheet = Parser.new.parse(input_file, options)
 
-      # Write the YAML data file with schema reference
-      File.write(output_yaml, comment_sheet.to_yaml_document(schema_dir))
+      schema_target = write_sheet(comment_sheet, options[:output], options[:schema_dir])
 
-      # Copy schema file to output directory
-      schema_name = comment_sheet.schema_name
-      schema_source = File.join(__dir__, "../../schema/#{schema_name}")
-      schema_target = File.join(schema_dir, schema_name)
-
-      # Only copy if source and target are different
-      FileUtils.cp(schema_source, schema_target) unless File.expand_path(schema_source) == File.expand_path(schema_target)
-
-      puts "Converted #{input_file} to #{output_yaml}"
+      puts "Converted #{input_file} to #{options[:output]}"
       puts "  Version: #{comment_sheet.version}"
       puts "  Comments: #{comment_sheet.comments.length}"
       puts "  Schema: #{schema_target}"
     end
 
+    desc "merge INPUT.yaml...", "Merge multiple comment sheets into one ballot sheet"
+    option :output, type: :string, aliases: :o, default: "merged.yaml", desc: "Output YAML file"
+    option :schema_dir, type: :string, default: "schema", desc: "Directory for schema file"
+    def merge(*input_files)
+      raise "At least one input file is required" if input_files.empty?
+
+      sheets = input_files.map { |path| CommentSheet.from_yaml(File.read(path)) }
+      comment_sheet = Ballot.new(sheets).merge
+      write_sheet(comment_sheet, options[:output], options[:schema_dir])
+
+      puts "Merged #{input_files.length} files (#{comment_sheet.comments.length} comments) to #{options[:output]}"
+    end
+
+    desc "stats INPUT.yaml", "Disposition statistics for ballot reports"
+    option :output, type: :string, aliases: :o, desc: "Output file (default: stdout)"
+    option :format, type: :string, default: "markdown", enum: %w[markdown yaml], desc: "Report format"
+    def stats(input_yaml)
+      comment_sheet = CommentSheet.from_yaml(File.read(input_yaml))
+
+      report = if options[:format] == "yaml"
+                 BallotReport.counts(comment_sheet).to_yaml
+               else
+                 BallotReport.to_markdown(comment_sheet)
+               end
+
+      if options[:output]
+        File.write(options[:output], report)
+        puts "Wrote statistics to #{options[:output]}"
+      else
+        puts report
+      end
+    end
+
+    desc "diff BEFORE.yaml AFTER.yaml", "Compare two ballots (e.g. CD vs DIS) by comment ID"
+    option :output, type: :string, aliases: :o, desc: "Output file (default: stdout)"
+    option :format, type: :string, default: "markdown", enum: %w[markdown yaml], desc: "Report format"
+    def diff(before_yaml, after_yaml)
+      before_sheet = CommentSheet.from_yaml(File.read(before_yaml))
+      after_sheet = CommentSheet.from_yaml(File.read(after_yaml))
+
+      report = if options[:format] == "yaml"
+                 BallotDiff.diff(before_sheet, after_sheet).to_yaml
+               else
+                 BallotDiff.to_markdown(before_sheet, after_sheet)
+               end
+
+      if options[:output]
+        File.write(options[:output], report)
+        puts "Wrote comparison to #{options[:output]}"
+      else
+        puts report
+      end
+    end
+
     desc "fill INPUT.yaml", "Fill DOCX template from YAML comments"
     option :output, type: :string, aliases: :o, default: "filled_comments.docx", desc: "Output DOCX file"
     option :template, type: :string, aliases: :t, desc: "Custom template file"
@@ -55,23 +93,20 @@ module Commenter
     def fill(input_yaml)
       output_docx = options[:output]
 
-      # Load YAML data
-      data = YAML.load_file(input_yaml)
-
-      # Extract comments from the structure
-      comments = if data.is_a?(Hash)
-                   data["comments"] || data[:comments] || []
-                 else
-                   data || []
-                 end
-
+      comment_sheet = CommentSheet.from_yaml(File.read(input_yaml))
+      comments = comment_sheet.comments
       raise "No comments found in YAML file" if comments.empty?
 
       # Use default template if none specified
       template_path = options[:template] || File.join(__dir__, "../../data/iso_comment_template_2012-03.docx")
 
-      # Fill the template
-      Filler.new.fill(template_path, output_docx, comments, options)
+      # Fill the template, including the sheet metadata in the page header
+      fill_options = options.merge(
+        date: comment_sheet.date,
+        document: comment_sheet.document,
+        project: comment_sheet.project
+      ).compact
+      Filler.new.fill(template_path, output_docx, comments, fill_options)
       puts "Filled template to #{output_docx}"
     end
 
@@ -146,6 +181,66 @@ module Commenter
       exit 1
     end
 
+    desc "github-sync INPUT.yaml", "Synchronize comments with GitHub issues (YAML is the source of truth)"
+    option :config, type: :string, aliases: :c, required: true, desc: "GitHub configuration YAML file"
+    option :output, type: :string, aliases: :o, desc: "Output YAML file (default: update original)"
+    option :stage, type: :string, desc: "Override approval stage (WD/CD/DIS/FDIS/PRF/PUB)"
+    option :milestone, type: :string, desc: "Override milestone name or number"
+    option :assignee, type: :string, desc: "Override assignee GitHub handle"
+    option :title_template, type: :string, desc: "Custom title template"
+    option :body_template, type: :string, desc: "Custom body template"
+    option :dry_run, type: :boolean, desc: "Preview sync actions without applying them"
+    option :conflict, type: :string, default: "yaml", enum: %w[yaml github skip],
+                      desc: "Conflict policy: yaml re-renders the issue, " \
+                            "github keeps the issue content, skip reports and leaves it"
+    option :close_on_disposition, type: :boolean, default: true,
+                                  desc: "Close open issues whose comment has a recorded " \
+                                        "disposition"
+    def github_sync(input_yaml)
+      sync = GitHubSync.new(options[:config], options[:title_template], options[:body_template])
+
+      sync_options = {
+        stage: options[:stage],
+        milestone: options[:milestone],
+        assignee: options[:assignee],
+        conflict: options[:conflict],
+        close_on_disposition: options[:close_on_disposition],
+        dry_run: options[:dry_run],
+        output: options[:output]
+      }.compact
+      results = sync.sync(input_yaml, sync_options)
+
+      if options[:dry_run]
+        puts "DRY RUN - Planned sync actions:"
+        puts "=" * 50
+        results.each do |result|
+          issue = result[:issue_number] ? "issue ##{result[:issue_number]}" : "no issue yet"
+          puts "#{result[:comment_id]} (#{issue}): #{result[:actions].join(", ")}"
+        end
+        puts "-" * 30
+        puts "Based on the issue state last recorded in the YAML; run without --dry-run for a live pass."
+      else
+        puts "GitHub sync results:"
+        puts "=" * 40
+        results.each do |result|
+          case result[:status]
+          when :created then puts "\u2713 #{result[:comment_id]}: Created issue ##{result[:issue_number]} " \
+                                   "(#{result[:issue_url]})"
+          when :updated then puts "\u21bb #{result[:comment_id]}: Updated issue ##{result[:issue_number]} " \
+                                   "(#{result[:actions].join(", ")})"
+          when :closed then puts "\u2713 #{result[:comment_id]}: Closed issue ##{result[:issue_number]} (disposition recorded)"
+          when :updated_and_closed then puts "\u21bb\u2713 #{result[:comment_id]}: Updated and closed issue ##{result[:issue_number]}"
+          when :unchanged then puts "- #{result[:comment_id]}: Issue ##{result[:issue_number]} in sync"
+          when :error then puts "\u2717 #{result[:comment_id]}: Error - #{result[:message]}"
+          end
+        end
+        puts "Updated YAML file: #{options[:output] || input_yaml}"
+      end
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+
     desc "github-retrieve INPUT.yaml", "Retrieve observations from GitHub issues"
     option :config, type: :string, aliases: :c, required: true, desc: "GitHub configuration YAML file"
     option :output, type: :string, aliases: :o, desc: "Output YAML file (default: update original)"
@@ -212,5 +307,18 @@ module Commenter
     def self.exit_on_failure?
       true
     end
+
+    private
+
+    def write_sheet(comment_sheet, output_yaml, schema_dir)
+      FileUtils.mkdir_p(schema_dir) unless Dir.exist?(schema_dir)
+      File.write(output_yaml, comment_sheet.to_yaml_document(schema_dir))
+
+      schema_name = comment_sheet.schema_name
+      schema_source = File.join(__dir__, "../../schema/#{schema_name}")
+      schema_target = File.join(schema_dir, schema_name)
+      FileUtils.cp(schema_source, schema_target) unless File.expand_path(schema_source) == File.expand_path(schema_target)
+      schema_target
+    end
   end
 end