jobcompat 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b1df789562ba30ff3474a112bd44e602d68b833b7d34c92b936f8e508e20484
-  data.tar.gz: ba09c1c7f2ce1f22d44cf690559e395584be8492c5abbbad85d492281b6849cd
+  metadata.gz: fe462bfac086361d10bc4be2bb535045c131d0cbabb9037b437789684665eb29
+  data.tar.gz: ecc7ee3319c763957771f3eff973ae3f7ace1b5deb43fda27de694b9fea8531f
 SHA512:
-  metadata.gz: c4e50e2e13f1bc1d3a3e667b63a3865bd01260f8b9bd462db724c0aa44641fd555f191a3059548df2ca408e13a081d3daeb993e4a805a7b9617d79034a36643b
-  data.tar.gz: aff92fbf9b66f5320958497d79a07fbf0defe4b56f1da444fddf69340478f72677e2cad601c5e9951d4de5e76a27f71095ba741e2c0d437be42a8eec75f9413a
+  metadata.gz: 137621193e3cbbad8cc1c368718390ee4c65e7c0ed37a5ba2a2ae798b24d4fbd0aa05ba26673e26b968c44bb89cc36b6cfc2146bc11638eb2ead7e97d19c31a1
+  data.tar.gz: e91710462947c4376ccc8fcc3f3f167fc7dfd2e21e1fa9d61d0197d69538f4707aec557fb662c6a5ec2785bb4688744866545bbcd395734afb9dc3a97a15a55b

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.1 - 2026-11-07
+
+- Add optional `--explain` text output showing the evidence, decision, and boundary behind each surviving JC001–JC007 finding, including alias provenance for serialized identities.
+- Compatibility decisions, default text output, and JSON schema 3 content are unchanged; combining `--explain` with `--format json` fails with a config error before analysis.
+
 ## 0.3.0 - 2026-10-05
 
 - Recognize static Sidekiq compatibility aliases, including finite chains and supported namespaces, to preserve old serialized identities across worker renames.

data/README.md

@@ -36,10 +36,13 @@ From a Git repository containing native Sidekiq jobs:
 ```sh
 jobcompat check --base origin/main
 jobcompat check --base v0.1.0 --head HEAD --format json
+jobcompat check --base origin/main --explain
 ```
 
 Both refs resolve to commits. Staged and uncommitted changes are ignored. The command never checks out another revision or changes the working tree.
 
+`--explain` appends an `Explanation` section—evidence, decision, and boundary—to each remaining finding in text output. It shows why a rule fired from the static evidence jobcompat already collected: it runs no additional compatibility checks, cannot be combined with `--format json` (exit 2 config error), reports only static source evidence, and never turns an `unknown` result into a safety claim.
+
 ## Example output
 
 For a base one-argument producer and a HEAD worker that requires two arguments, text output includes:

data/SECURITY.md

@@ -2,4 +2,8 @@
 
 If you find a vulnerability, use this repository's GitHub private vulnerability reporting. Please avoid posting an exploitable report in a public issue.
 
-Supported release: 0.1.x after publication. Security fixes will be released as a new gem version rather than replacing an existing one.
+## Supported releases
+
+The latest published minor release series is supported for security fixes. Older versions may receive fixes at the maintainer's discretion.
+
+Security fixes are published as new gem versions. Existing published gem versions are not replaced.

data/docs/implementation-plan-v0.3.1.md

@@ -0,0 +1,54 @@
+# jobcompat v0.3.1 implementation plan
+
+Baseline: `02751a57e21da3f548f6d6442b17a438026ef9e1` (v0.3.0). All changes
+stay uncommitted for independent review.
+
+## Change order
+
+1. `lib/jobcompat/explanation.rb` (new): `Explanation = Data.define(:evidence, :decision, :boundary)` plus a private builder module used by the Engine. Evidence entries, decision, and boundary are plain frozen strings; rendering responsibility stays with the Formatter.
+2. `lib/jobcompat/engine.rb`: `evaluate(with_explanations: false)`. At each
+   finding site (JC001, JC002, JC003, JC004, JC005, JC006, presence-unknown
+   JC007, and the aggregated JC007 roots) build an `Explanation` from the
+   producer group, contracts, presence result, alias resolution, and unknown
+   root already in scope, and store it in a
+   `{}.compare_by_identity` sidecar keyed by the finding hash object. The
+   sidecar is returned as `explanations:` only when requested. Finding and
+   worker rows are not modified.
+3. `lib/jobcompat/formatter.rb`: `text(envelope, explanations: nil)`. When a
+   non-nil sidecar maps the finding, render the fixed `Explanation:` /
+   `Evidence:` / `Decision:` / `Boundary:` block between the location lines
+   and `Suggested migration:`. `explanations: nil` keeps output
+   byte-identical. `json` untouched.
+4. `lib/jobcompat/cli.rb`: parse `--explain` (default false); reject
+   `--explain` with non-text format as `config_error` before repository
+   access; pass `with_explanations:` to `evaluate` and `explanations:` to
+   `Formatter.text` for the completed text path only.
+5. `lib/jobcompat/version.rb` -> 0.3.1; `Gemfile.lock` path spec version.
+6. `docs/spec-v0.3.1.md` (normative delta), this plan, README quick-start and
+   explanation notes, `CHANGELOG.md` `## 0.3.1 - Unreleased`.
+
+## Test order
+
+1. Unit `test/unit/explanation_test.rb`: Explanation VO shape; formatter
+   parity (nil sidecar byte-identical, unknown finding -> no section);
+   sanitization of hostile strings.
+2. Integration `test/integration/explain_command_test.rb`: CLI contract
+   (accept/combos/order/json rejection/failed envelope schema 3/help);
+   per-rule content for JC001 (both direction variants, alias-carried
+   identity), JC002, JC003 (no base leakage), JC004 (absence only;
+   outside-scope fixture must not claim absence), JC005 (conditional
+   rolling-deploy wording, Class-object terminal identity, exact Client
+   String identity), JC006 (no empty-queue claim), JC007 (alias cycle,
+   unresolved, splat producer, keyword contract); suppression behavior;
+   zero-finding behavior; determinism double-run; default-output regression
+   against committed expectations derived from the frozen 0.3.0 baselines.
+3. Full suite `rake test`; baseline runner `compare` (byte-identical after
+   version normalization only).
+4. `gem build`, package content inspection, isolated install, CLI smoke.
+
+## Regression evidence
+
+Frozen 0.3.0 outputs for JC001–JC007 (including alias-carried, client-string,
+and outside-scope variants), resolved alias rename, targeted suppression, and
+a no-findings comparison were captured before implementation and are
+re-compared after; only the version string may differ.

data/docs/spec-v0.3.1.md

@@ -0,0 +1,202 @@
+# jobcompat v0.3.1 delta specification
+
+Status: normative for 0.3.1. This document extends `spec-v0.3.md` (which extends
+`spec-v0.2.1.md`, `spec-v0.2.md`, and `spec-v0.1.md`) with the optional text
+`--explain` output. It adds display capability only. It changes no
+compatibility decision, JSON contract, or exit status policy.
+
+## Version and schema contracts
+
+Gem and CLI version: 0.3.1. Completed and failed JSON envelopes continue to
+use `schema_version: 3` with the same fields and ordering as 0.3.0.
+`.jobcompat.yml` continues to use config version 1. Ruby >= 3.3 and
+prism >= 1.9, < 2 are unchanged, and no runtime dependency is added.
+
+JC001–JC007 semantics, severities, comparison directions, finding precedence,
+finding deduplication, semantic fingerprints, producer identity resolution,
+alias resolution, presence budget, suppression matching, and exit status
+policy are unchanged.
+
+## CLI contract
+
+`jobcompat check --base REF --explain` is accepted, as are
+`--format text --explain` and `--explain --format text` in either order.
+Option order must not change results.
+
+`--format json --explain` (either order) is rejected before any Git or
+parse work: exit 2, category `config_error`, message
+`--explain is supported only with --format text`, and the regular JSON
+failed envelope with `schema_version: 3` on stdout. No stack trace or
+internal exception reaches stderr.
+
+`check --help` lists `--explain` with the description
+`Explain the evidence behind each finding (text only)`. Top-level
+`--help` and `--version` output is unchanged except the version string.
+
+All existing failure categories (config_error, parse_error, Git errors,
+internal_error) keep their existing streams, exit code 2, diagnostics
+sanitization, and produce no Explain-specific additional diagnostics.
+
+## Explain scope
+
+`--explain` explains only public findings that remain after targeted
+suppression. Suppressed finding bodies receive no explanation. Internal
+unreported candidates, producers that never became findings, repository
+coverage, runtime queue contents, and hypothetical dynamic producers are out
+of scope. Suppression audit lines, counts, order, and reasons are unchanged.
+
+When no findings remain, the existing PASS (or PASS WITH WARNINGS) output is
+emitted with no Explanation heading or section.
+
+## Rendering contract
+
+For each remaining finding, an Explanation section is inserted between the
+finding's source location list and `Suggested migration:`. All pre-existing
+lines (severity, rule ID, worker, message, Revisions, Reason, Affected
+directions, Risk, locations, remediation, summary, suppression audit) keep
+their content, order, indentation, newlines, and trailing newline. The
+section uses fixed headings:
+
+```text
+  Explanation:
+    Evidence:
+    Decision:
+    Boundary:
+```
+
+`Evidence` contains one or more verified facts used by the decision.
+`Decision` states the rule that produced the finding. `Boundary` states what
+the evidence cannot prove, including conditional assumptions. Each finding
+receives at most one Explanation. Every line passes the existing
+`Formatter.safe_line` sanitization.
+
+Without `--explain`, text output is byte-for-byte identical to 0.3.0 apart
+from the version string, and JSON output is byte-for-byte identical to 0.3.0
+apart from `tool.version`.
+
+## Per-rule explanation obligations
+
+Each Explanation is built from the facts the Engine actually used at the
+finding site.
+
+- JC001: BASE producer's decided payload arity, the BASE consumer acceptance,
+  the HEAD consumer rejection, and—if `head_to_head` is among the
+  directions—a HEAD producer witness of the same arity. No HEAD witness is
+  claimed when the direction is absent. Boundary: retained queue contents are
+  not inspected.
+- JC002: HEAD producer's decided arity, HEAD consumer acceptance, BASE
+  consumer rejection. Boundary: whether an old process consumes the relevant
+  queue, and when it retires, is not statically determined.
+- JC003: HEAD producer arity and HEAD consumer rejection only; unrelated
+  base-revision evidence must not appear. JC001/JC003 precedence is
+  unchanged.
+- JC004: BASE-recognized serialized identity, the conservative HEAD absence
+  proof, and provenance. `defined_unrecognized`, `outside_scan_scope`, and
+  `unverified` presence statuses are never described as absence. Boundary:
+  static absence does not mean the queue is empty.
+- JC005: the decided HEAD serialized identity, HEAD recognition, and the
+  BASE absence proof. The rolling-deploy failure is conditional on an old
+  process consuming the relevant queue; it is never stated as unconditional.
+  A known producer identity suffices when payload arity is unknown. A
+  Class-object alias producer is explained under its terminal serialized
+  identity, and an exact Client String identity is never rewritten.
+- JC006: BASE contract, HEAD contract, the removed acceptance ranges, and
+  the absence of a qualifying producer witness. Boundary: missing producer
+  witnesses do not prove absence of queued, scheduled, retried, historical,
+  or externally enqueued payloads; no safety or compatibility claim is made.
+- JC007: the existing `unknown_reason`, revision(s), direction(s), and the
+  source provenance used for the diagnosis. Unknown or unsupported evidence
+  is never presented as proof of compatibility. No new unknown reason is
+  introduced. The alias reasons `alias_target_unresolved`, `alias_cycle`,
+  `alias_binding_conflict`, and `unsupported_alias_assignment` are reported
+  as-is, and an undetermined alias terminal is never presented as resolved.
+
+## Alias semantics
+
+Serialized identity rules follow 0.3.0. A Class-object producer through an
+alias serializes as the terminal Class name; an exact Client String keeps
+its exact identity. Explanation text never substitutes a source alias token
+for a serialized identity or vice versa.
+
+For findings whose evidence involves an alias, Explanation may include one
+line per relevant revision, using only the existing `AliasResolution`
+result:
+
+```text
+Alias (HEAD): OldJob -> MiddleJob -> NewJob (resolved).
+Alias (HEAD): unresolved (alias_cycle).
+```
+
+The Engine never re-walks the alias graph for explanations.
+
+## Proof model and isolation
+
+Explanations are produced by the Engine at the sites where findings are
+decided, using the producer groups, consumer contracts, presence results,
+alias resolutions, and unknown roots already computed. Re-running
+`Contract#accepts?`, re-walking alias graphs, re-proving absence,
+re-extracting producers, or parsing finding messages to recover evidence is
+prohibited.
+
+The Engine exposes `evaluate(with_explanations: false)`. The default return
+value is unchanged. With `with_explanations: true` the result additionally
+carries an internal explanation sidecar keyed by finding object identity, so
+multiple findings of the same rule and worker, JC007 deduplication groups,
+and post-suppression survivors remain correctly paired. Object identity is
+internal only; no identifier is printed or serialized. Findings and worker
+rows never gain an `explanation` key, and the sidecar never reaches JSON.
+
+`Formatter.text(envelope, explanations: nil)` renders the section only when
+a non-nil sidecar maps the finding. `explanations: nil` keeps output
+byte-identical. `Formatter.json` is unchanged.
+Suppression continues to run after evaluation and before formatting;
+explanations are displayed only for surviving findings.
+
+Call-site counts in Evidence count distinct enqueue locations, keyed by
+revision, path, line, and column. Location role is not part of that identity,
+worker declarations and alias assignments are never counted, and multiple
+arities or known/unknown records originating from one enqueue location count
+once, so one bulk enqueue with several rows is one call site.
+
+## Determinism and security
+
+For the same repository state, configuration, and command, repeated runs
+produce byte-identical stdout, byte-identical stderr, and identical exit
+codes, with and without `--explain`. Explanation construction avoids
+insertion-order dependence, uses the existing stable location and chain
+ordering, emits no timestamps, randomness, object IDs, or absolute temporary
+paths, performs no Unicode normalization, and cannot inject raw newlines,
+ANSI escapes, or Unicode format controls (existing `safe_line` escaping
+applies). Error-path secret sanitization and stdout/stderr responsibilities
+are unchanged.
+
+## Test acceptance criteria
+
+- CLI: `--explain` accepted alone and with `--format text` in both orders;
+  `--format json --explain` rejected with exit 2, `config_error`, schema 3
+  failed envelope; help lists `--explain`; help/version unchanged; invalid
+  config, invalid ref, and parse errors keep existing failure contracts.
+- JC001–JC007: per-rule evidence content, precedence, absence conservatism,
+  conditional rolling-deploy wording for JC005, no empty-queue claims for
+  JC006, unknown-not-compatible for JC007.
+- Alias: resolved BASE/HEAD chains, finite chains, unsupported and unknown
+  aliases, direct workers, and Class-object versus exact String contrast.
+- Suppression: suppressed findings receive no Explanation; surviving
+  findings do; audit unchanged.
+- Backward compatibility: default text byte-identical to 0.3.0 fixtures
+  except the version string; JSON identical except `tool.version`;
+  normalized comparison must not mask findings, summary, provenance, or
+  unknown reasons.
+- Determinism/security: double-run stdout/stderr/exit equality, control
+  characters, ANSI escapes, Unicode format controls, Unicode worker names,
+  newlines in refs, dirty worktree neutrality, no source execution, no
+  network.
+- No findings: exit 0 with no added Explanation output; warning-only exit 0;
+  any errors exit 1.
+
+## Non-goals
+
+No new compatibility rule, severity, direction, unknown reason, JSON field,
+config key, dependency, queue/runtime simulation, heuristic rename
+detection, or change to existing normative specifications. Explanations do
+not restate suppressed findings and do not estimate runtime behavior.

data/lib/jobcompat/cli.rb

@@ -9,6 +9,7 @@ module Jobcompat
     def initialize(args, stdout, stderr, directory)
       @args, @stdout, @stderr, @directory = args.dup, stdout, stderr, directory
       @base, @head, @format, @config_path = nil, "HEAD", "text", nil
+      @explain = false
       @base_sha = @head_sha = @loaded_config = nil
     end
 
@@ -22,12 +23,14 @@ module Jobcompat
         options.on("--head REF", "Head commit-ish (default HEAD)") { |value| @head = value }
         options.on("--format FORMAT", "text or json") { |value| @format = value }
         options.on("--config PATH", "Config YAML path") { |value| @config_path = value }
+        options.on("--explain", "Explain the evidence behind each finding (text only)") { @explain = true }
         options.on("-h", "--help", "Show help") { @stdout.puts(options); return 0 }
       end
       parser.parse!(@args)
       raise Error.new("Unexpected arguments: #{@args.join(' ')}", category: "config_error") unless @args.empty?
       raise Error.new("--base is required", category: "config_error") unless @base && !@base.empty?
       raise Error.new("--format must be text or json", category: "config_error") unless %w[text json].include?(@format)
+      raise Error.new("--explain is supported only with --format text", category: "config_error") if @explain && @format != "text"
       repository = GitRepository.new(@directory)
       config = Config.load(root: repository.root, explicit: @config_path, invocation_dir: @directory)
       @loaded_config = config.display_path
@@ -57,7 +60,7 @@ module Jobcompat
       requests = engine.presence_requests
       head.check_presence(requests["head"], repository, config)
       base.check_presence(requests["base"], repository, config)
-      result = engine.evaluate
+      result = engine.evaluate(with_explanations: @explain)
       findings, suppressions = config.suppressions(result[:findings])
       summary = {
         errors: findings.count { |item| item[:severity] == "error" }, warnings: findings.count { |item| item[:severity] == "warning" },
@@ -67,7 +70,13 @@ module Jobcompat
         enqueue_calls: {base: base.calls.length, head: head.calls.length,
                         unknown: engine.calls.values.flatten.count { |call| call[:reason] }}
       }
-      @stdout.write(Formatter.public_send(@format, envelope("completed", findings, suppressions, result[:workers], [], summary)))
+      completed = envelope("completed", findings, suppressions, result[:workers], [], summary)
+      output = if @format == "json"
+        Formatter.json(completed)
+      else
+        Formatter.text(completed, explanations: @explain ? result[:explanations] : nil)
+      end
+      @stdout.write(output)
       summary[:errors].positive? ? 1 : 0
     rescue OptionParser::ParseError => error
       failure(Error.new(error.message, category: "config_error"))

data/lib/jobcompat/engine.rb

@@ -32,8 +32,9 @@ module Jobcompat
       @presence_requests
     end
 
-    def evaluate
+    def evaluate(with_explanations: false)
       findings = []
+      explanations = {}.compare_by_identity
       workers = @names.map do |name|
         b = base.consumer(name)
         h = head.consumer(name)
@@ -43,22 +44,32 @@ module Jobcompat
         head_presence = presence(head, name, h, presence_requests["head"].include?(name))
         if b && !h
           if head_presence == "absent"
-            findings << finding("JC004", name, ["base", "head"], ["base_to_head"], nil, nil,
-                                "The serialized worker identity is absent from HEAD tracked Ruby source.",
-                                "Queued, retried, or scheduled jobs may still reference this class name.",
-                                ["Keep the worker class or a supported compatibility alias until retained jobs can no longer run."],
-                                b.declaration_locations + contract_proof(b) + producer_proof(hc))
-          else
-            findings << presence_unknown(name, head_presence, b.declaration_locations + head.index.locations(name), "base_to_head", "head") unless head.aliases.key?(name)
+            item = finding("JC004", name, ["base", "head"], ["base_to_head"], nil, nil,
+                           "The serialized worker identity is absent from HEAD tracked Ruby source.",
+                           "Queued, retried, or scheduled jobs may still reference this class name.",
+                           ["Keep the worker class or a supported compatibility alias until retained jobs can no longer run."],
+                           b.declaration_locations + contract_proof(b) + producer_proof(hc))
+            findings << item
+            explanations[item] = ExplanationBuilder.jc004(worker: name, base_contract: b, head_producers: hc,
+                                                           aliases: alias_provenance(name)) if with_explanations
+          elsif !head.aliases.key?(name)
+            item = presence_unknown(name, head_presence, b.declaration_locations + head.index.locations(name), "base_to_head", "head")
+            findings << item
+            explanations[item] = ExplanationBuilder.presence_unknown(worker: name, status: head_presence, revision: "head") if with_explanations
           end
         elsif h && !b && !hc.empty?
           if base_presence == "absent"
-            findings << finding("JC005", name, ["base", "head"], ["head_to_base"], nil, nil,
-                                "HEAD can enqueue a serialized worker identity absent from base tracked Ruby source.",
-                                "If an old Sidekiq process can consume this job during the rolling deployment, it cannot resolve the new worker class.",
-                                ["Deploy the worker class or compatibility alias before activating its producer."], h.declaration_locations + producer_proof(hc))
-          else
-            findings << presence_unknown(name, base_presence, h.declaration_locations + base.index.locations(name), "head_to_base", "base") unless base.aliases.key?(name)
+            item = finding("JC005", name, ["base", "head"], ["head_to_base"], nil, nil,
+                           "HEAD can enqueue a serialized worker identity absent from base tracked Ruby source.",
+                           "If an old Sidekiq process can consume this job during the rolling deployment, it cannot resolve the new worker class.",
+                           ["Deploy the worker class or compatibility alias before activating its producer."], h.declaration_locations + producer_proof(hc))
+            findings << item
+            explanations[item] = ExplanationBuilder.jc005(worker: name, head_contract: h, head_calls: hc,
+                                                          aliases: alias_provenance(name)) if with_explanations
+          elsif !base.aliases.key?(name)
+            item = presence_unknown(name, base_presence, h.declaration_locations + base.index.locations(name), "head_to_base", "base")
+            findings << item
+            explanations[item] = ExplanationBuilder.presence_unknown(worker: name, status: base_presence, revision: "base") if with_explanations
           end
         end
 
@@ -72,10 +83,13 @@ module Jobcompat
             directions = ["base_to_head"]
             directions << "head_to_head" unless head_same.empty?
             locations = producer_proof(group) + contract_proof(b) + contract_proof(h) + producer_proof(head_same)
-            findings << finding("JC001", name, head_same.empty? ? ["base", "head"] : ["base", "head"], directions, arity, nil,
-                                "Base emits #{arity} #{argument_word(arity)}, but the HEAD worker accepts #{h.display_range}.",
-                                "Jobs queued by the base revision may fail after deployment.",
-                                ["Make the HEAD worker accept old payloads.", "Narrow only after queue, retry, and schedule retention is handled."], locations)
+            item = finding("JC001", name, head_same.empty? ? ["base", "head"] : ["base", "head"], directions, arity, nil,
+                           "Base emits #{arity} #{argument_word(arity)}, but the HEAD worker accepts #{h.display_range}.",
+                           "Jobs queued by the base revision may fail after deployment.",
+                           ["Make the HEAD worker accept old payloads.", "Narrow only after queue, retry, and schedule retention is handled."], locations)
+            findings << item
+            explanations[item] = ExplanationBuilder.jc001(arity: arity, base_contract: b, head_contract: h, head_witness: !head_same.empty?,
+                                                          aliases: alias_provenance(name)) if with_explanations
             proven_narrow = true
           end
         end
@@ -84,17 +98,23 @@ module Jobcompat
           head_groups.sort.each do |arity, group|
             if !h.accepts?(arity)
               next if findings.any? { |item| item[:rule_id] == "JC001" && item[:worker] == name && item[:payload_arity] == arity }
-              findings << finding("JC003", name, ["head"], ["head_to_head"], arity, nil,
-                                  "HEAD emits #{arity} #{argument_word(arity)}, but its worker accepts #{h.display_range}.",
-                                  "Current HEAD jobs can fail when executed.", ["Align the enqueue payload with the HEAD perform signature."],
-                                  producer_proof(group) + contract_proof(h))
+              item = finding("JC003", name, ["head"], ["head_to_head"], arity, nil,
+                             "HEAD emits #{arity} #{argument_word(arity)}, but its worker accepts #{h.display_range}.",
+                             "Current HEAD jobs can fail when executed.", ["Align the enqueue payload with the HEAD perform signature."],
+                             producer_proof(group) + contract_proof(h))
+              findings << item
+              explanations[item] = ExplanationBuilder.jc003(arity: arity, head_contract: h,
+                                                            aliases: alias_provenance(name, head)) if with_explanations
               current_removed_witness ||= b&.known? && b.accepts?(arity)
             elsif b&.known? && !b.accepts?(arity)
-              findings << finding("JC002", name, ["base", "head"], ["head_to_base"], arity, nil,
-                                  "HEAD emits #{arity} #{argument_word(arity)}, but the base worker accepts #{b.display_range}.",
-                                  "A new producer can enqueue work that an old worker cannot execute during a rolling deploy.",
-                                  ["Deploy the optional worker argument first.", "Start enqueueing the new argument in a later release."],
-                                  producer_proof(group) + contract_proof(b) + contract_proof(h))
+              item = finding("JC002", name, ["base", "head"], ["head_to_base"], arity, nil,
+                             "HEAD emits #{arity} #{argument_word(arity)}, but the base worker accepts #{b.display_range}.",
+                             "A new producer can enqueue work that an old worker cannot execute during a rolling deploy.",
+                             ["Deploy the optional worker argument first.", "Start enqueueing the new argument in a later release."],
+                             producer_proof(group) + contract_proof(b) + contract_proof(h))
+              findings << item
+              explanations[item] = ExplanationBuilder.jc002(arity: arity, base_contract: b, head_contract: h,
+                                                            aliases: alias_provenance(name)) if with_explanations
             end
           end
         end
@@ -102,11 +122,14 @@ module Jobcompat
           unless h.superset_of?(b) || proven_narrow || current_removed_witness
             removed = removed_arity_ranges(b, h)
             label = removed.length == 1 && removed.first.match?(/\A\d+\z/) ? "arity" : "arities"
-            findings << finding("JC006", name, ["base", "head"], ["base_to_head"], nil, nil,
-                                "The HEAD worker removed #{label} #{removed.join(', ')} from the base contract; no qualifying producer witness was found.",
-                                "No repository producer callsite found does not prove that no queued, scheduled, retried, historical, or externally enqueued payload exists.",
-                                ["Keep the broader signature through the retention window, or document a proven drain."],
-                                contract_proof(b) + contract_proof(h))
+            item = finding("JC006", name, ["base", "head"], ["base_to_head"], nil, nil,
+                           "The HEAD worker removed #{label} #{removed.join(', ')} from the base contract; no qualifying producer witness was found.",
+                           "No repository producer callsite found does not prove that no queued, scheduled, retried, historical, or externally enqueued payload exists.",
+                           ["Keep the broader signature through the retention window, or document a proven drain."],
+                           contract_proof(b) + contract_proof(h))
+            findings << item
+            explanations[item] = ExplanationBuilder.jc006(worker: name, base_contract: b, head_contract: h, removed: removed,
+                                                          aliases: alias_provenance(name)) if with_explanations
           end
         end
 
@@ -121,9 +144,11 @@ module Jobcompat
                           head_to_base: cell(hc, b, base_presence), head_to_head: cell(hc, h, head_presence)}
         }
       end
-      findings.concat(unknown_findings)
+      findings.concat(unknown_findings(explanations: with_explanations ? explanations : nil))
       findings = findings.sort_by { |item| finding_sort_key(item) }
-      {findings: findings, workers: workers}
+      result = {findings: findings, workers: workers}
+      result[:explanations] = explanations if with_explanations
+      result
     end
 
     private
@@ -189,6 +214,17 @@ module Jobcompat
 
     def producer_proof(group) = group.flat_map { |call| call[:locations] }
 
+    def alias_provenance(name, *snapshots)
+      snapshots = [base, head] if snapshots.empty?
+      snapshots.filter_map do |snapshot|
+        binding = snapshot.aliases[name]
+        next unless binding
+        chain = binding.chain.join(" -> ")
+        binding.resolved? ? "Alias (#{snapshot.label.upcase}): #{chain} (resolved)." :
+          "Alias (#{snapshot.label.upcase}): #{chain.length > 1 ? chain : "unresolved"} (#{binding.unknown_reason})."
+      end
+    end
+
     def contract_proof(contract)
       return contract.locations if base.aliases.key?(contract.name) || head.aliases.key?(contract.name)
       contract.locations.select { |location| location.role == "consumer" }
@@ -236,7 +272,7 @@ module Jobcompat
               ["Restore a directly recognized worker declaration, or inspect the deployment manually."], locations)
     end
 
-    def unknown_findings
+    def unknown_findings(explanations: nil)
       roots = []
       [base, head].each do |snapshot|
         @names.each do |name|
@@ -251,7 +287,8 @@ module Jobcompat
           producer_locations = calls[snapshot.label].select { |call| call[:identity_reason] && call[:attributed_worker] == name }.flat_map { |call| call[:locations] }
           roots << {revision: snapshot.label, kind: "consumer_alias", reason: binding.unknown_reason, worker: name,
                     locations: binding.locations + producer_locations,
-                    parts: ["consumer_alias", binding.unknown_reason, name, binding.fingerprint_parts, binding.chain], offset: 0}
+                    parts: ["consumer_alias", binding.unknown_reason, name, binding.fingerprint_parts, binding.chain],
+                    chain: binding.chain, offset: 0}
         end
         snapshot.unknowns.each do |item|
           roots << {revision: snapshot.label, kind: item.kind, reason: item.reason, worker: item.worker,
@@ -294,9 +331,11 @@ module Jobcompat
         message = alias_reason ? alias_message(first[:worker], first[:reason]) : "#{first[:reason]} prevents a complete positional compatibility check."
         risk = alias_reason ? "Compatibility for jobs serialized as #{first[:worker]} cannot be proven from selected source." : "The affected producer or consumer contract is unknown."
         remediation = alias_reason ? ["Use one explicit static alias if it matches runtime behavior, or inspect the deployment manually."] : ["Use supported explicit syntax or inspect this call manually."]
-        finding("JC007", first[:worker], group.map { |root| root[:revision] }.uniq, directions, nil, first[:reason],
-                message, risk, remediation,
-                group.flat_map { |root| root[:locations] })
+        item = finding("JC007", first[:worker], group.map { |root| root[:revision] }.uniq, directions, nil, first[:reason],
+                       message, risk, remediation,
+                       group.flat_map { |root| root[:locations] })
+        explanations[item] = ExplanationBuilder.unknown_group(roots: group, message: message) if explanations
+        item
       end
     end
 

data/lib/jobcompat/explanation.rb

@@ -0,0 +1,144 @@
+module Jobcompat
+  Explanation = Data.define(:evidence, :decision, :boundary)
+
+  module ExplanationBuilder
+    REVISION_LABELS = {"base" => "BASE", "head" => "HEAD"}.freeze
+
+    module_function
+
+    def jc001(arity:, base_contract:, head_contract:, head_witness:, aliases:)
+      evidence = [
+        "BASE producer emits #{arity} positional #{argument_word(arity)}.",
+        "BASE consumer accepts #{arity} positional #{argument_word(arity)} (#{range(base_contract)}).",
+        "HEAD consumer accepts #{range(head_contract)} positional #{range_word(head_contract)}, rejecting #{arity}."
+      ]
+      evidence << "HEAD producer also emits #{arity} positional #{argument_word(arity)}, enqueuing the same payload shape." if head_witness
+      decision = "A payload accepted in BASE (#{arity} positional #{argument_word(arity)}) is rejected by the HEAD worker (#{range(head_contract)})."
+      decision << " HEAD producers still enqueue the same arity." if head_witness
+      build(evidence + aliases, decision,
+            "Static arity evidence; actual retained queue contents are not inspected.")
+    end
+
+    def jc002(arity:, base_contract:, head_contract:, aliases:)
+      evidence = [
+        "HEAD producer emits #{arity} positional #{argument_word(arity)}.",
+        "HEAD consumer accepts #{range(head_contract)} positional #{range_word(head_contract)}.",
+        "BASE consumer accepts #{range(base_contract)} positional #{range_word(base_contract)}, rejecting #{arity}."
+      ]
+      build(evidence + aliases,
+            "A payload enqueued by HEAD (#{arity} positional #{argument_word(arity)}) would be rejected by the base worker if an old process executes it during the rolling deployment.",
+            "Whether an old process consumes this queue, and when it retires, is not determined by static analysis.")
+    end
+
+    def jc003(arity:, head_contract:, aliases:)
+      evidence = [
+        "HEAD producer emits #{arity} positional #{argument_word(arity)}.",
+        "HEAD consumer accepts #{range(head_contract)} positional #{range_word(head_contract)}, rejecting #{arity}."
+      ]
+      build(evidence + aliases,
+            "HEAD's own producer and consumer disagree on payload arity.",
+            "Static arity evidence within HEAD; base-revision evidence does not affect this finding.")
+    end
+
+    def jc004(worker:, base_contract:, head_producers:, aliases:)
+      evidence = [consumer_fact("base", worker, base_contract),
+                  "HEAD conservative presence check across tracked Ruby source proved #{worker} absent."]
+      evidence << "HEAD still contains #{call_sites(distinct_call_sites(head_producers))} referencing this identity." if head_producers.any?
+      build(evidence + aliases,
+            "A retained job serialized as #{worker} cannot be resolved to a worker by HEAD tracked Ruby source.",
+            "Static absence does not prove the queue is empty; queued, retried, scheduled, historical, or externally enqueued jobs may still reference this identity.")
+    end
+
+    def jc005(worker:, head_contract:, head_calls:, aliases:)
+      evidence = ["HEAD producer can enqueue the serialized worker identity #{worker} (#{call_sites(distinct_call_sites(head_calls))})."]
+      head_calls.map { |call| call[:attributed_worker] }.compact.uniq.sort.reject { |name| name == worker }.each do |name|
+        evidence << "HEAD Class-object producer #{name} serializes as the terminal identity #{worker}."
+      end
+      evidence << "HEAD Client String producer keeps the exact identity #{worker}." if head_calls.any? { |call| call[:raw].resolution_mode == "exact_string" }
+      known = head_calls.filter_map { |call| call[:arity] unless call[:reason] }.uniq.sort
+      evidence << "Known HEAD payload arities for this identity: #{known.join(', ')}." if known.any?
+      evidence << consumer_fact("head", worker, head_contract)
+      evidence << "BASE conservative presence check across tracked Ruby source proved #{worker} absent."
+      build(evidence + aliases,
+            "If an old Sidekiq process consumes this job's queue during the rolling deployment, it cannot resolve the serialized identity #{worker}.",
+            "This does not prove unconditional failure; the risk is conditional on an old process consuming the relevant queue before retirement, which static analysis cannot determine.")
+    end
+
+    def jc006(worker:, base_contract:, head_contract:, removed:, aliases:)
+      evidence = [
+        consumer_fact("base", worker, base_contract),
+        consumer_fact("head", worker, head_contract),
+        "HEAD no longer accepts #{removed.length == 1 && removed.first.match?(/\A\d+\z/) ? "arity" : "arities"} #{removed.join(', ')}.",
+        "No qualifying producer witness was found for the removed range in either revision."
+      ]
+      build(evidence + aliases,
+            "The worker contract narrowed from #{range(base_contract)} to #{range(head_contract)} without a qualifying producer witness.",
+            "No repository producer witness does not prove that no queued, scheduled, retried, historical, or externally enqueued payload exists.")
+    end
+
+    def presence_unknown(worker:, status:, revision:)
+      label = REVISION_LABELS.fetch(revision)
+      fact = case status
+             when "defined_unrecognized" then "#{worker} is defined in #{label} selected source, but is not recognized as a Sidekiq worker."
+             when "outside_scan_scope" then "#{worker} is declared only outside the scan scope in #{label}."
+             when "unverified" then "Presence of #{worker} in #{label} could not be verified within the analysis budget."
+             end
+      build([fact],
+            "The Sidekiq contract for #{worker} is not recognized, so this transition cannot be proven.",
+            "Unknown is not a proof of compatibility; the affected evidence was excluded from the compatibility decision.")
+    end
+
+    def unknown_group(roots:, message:)
+      build(roots.map { |root| root_fact(root) }, message,
+            "Unknown or unsupported evidence is not a proof of compatibility; the affected calls or contracts were excluded from the compatibility decision.")
+    end
+
+    def root_fact(root)
+      label = REVISION_LABELS.fetch(root[:revision])
+      case root[:kind]
+      when "consumer_contract" then "#{label}: the consumer contract for #{root[:worker]} is unknown (#{root[:reason]})."
+      when "consumer_alias"
+        chain = root[:chain]
+        path = chain && chain.length > 1 ? chain.join(" -> ") : "unresolved"
+        "Alias (#{label}): #{path} (#{root[:reason]})."
+      when "worker_identity" then "#{label}: a Sidekiq-including class is declared through an unsupported constant path."
+      when "producer_receiver"
+        root[:worker] ? "#{label}: the producer receiver for #{root[:worker]} could not be resolved (#{root[:reason]})." :
+          "#{label}: a producer receiver could not be resolved (#{root[:reason]})."
+      when "producer_arity"
+        root[:worker] ? "#{label}: the payload arity for #{root[:worker]} could not be determined (#{root[:reason]})." :
+          "#{label}: a producer payload arity could not be determined (#{root[:reason]})."
+      end
+    end
+
+    def consumer_fact(revision, worker, contract)
+      contract.known? ?
+        "#{REVISION_LABELS.fetch(revision)} consumer #{worker} accepts #{range(contract)} positional #{range_word(contract)}." :
+        "#{REVISION_LABELS.fetch(revision)} consumer #{worker} has an unknown contract (#{contract.unknown_reason})."
+    end
+
+    def range_word(contract)
+      contract.display_range.match?(/\A\d+\z/) ? argument_word(contract.display_range.to_i) : "arguments"
+    end
+
+    def range(contract)
+      contract.display_range
+    end
+
+    def argument_word(number)
+      number == 1 ? "argument" : "arguments"
+    end
+
+    def call_sites(number)
+      "#{number} call site#{number == 1 ? '' : 's'}"
+    end
+
+    def distinct_call_sites(calls)
+      calls.map { |call| call[:location] }.uniq { |location| [location.revision, location.path, location.line, location.column] }.length
+    end
+
+    def build(evidence, decision, boundary)
+      Explanation.new(evidence.freeze, decision, boundary).freeze
+    end
+  end
+end

data/lib/jobcompat/formatter.rb

@@ -15,7 +15,7 @@ module Jobcompat
       end
     end
 
-    def self.text(envelope)
+    def self.text(envelope, explanations: nil)
       return envelope[:diagnostics].map { |item| safe_line("#{item[:category]}: #{item[:message]}") }.join("\n") + "\n" if envelope[:status] == "failed"
       base = envelope[:comparison][:base]
       head = envelope[:comparison][:head]
@@ -35,6 +35,16 @@ module Jobcompat
           finding[:locations].each do |location|
             lines << "  #{location.revision} #{location.path}:#{location.line}:#{location.column} (#{location.role})"
           end
+          explanation = explanations && explanations[finding]
+          if explanation
+            lines << "  Explanation:"
+            lines << "    Evidence:"
+            explanation.evidence.each { |fact| lines << "      #{fact}" }
+            lines << "    Decision:"
+            lines << "      #{explanation.decision}"
+            lines << "    Boundary:"
+            lines << "      #{explanation.boundary}"
+          end
           lines << "  Suggested migration:"
           finding[:remediation].each_with_index { |step, index| lines << "    #{index + 1}. #{step}" }
           lines << ""

data/lib/jobcompat/version.rb

@@ -1,3 +1,3 @@
 module Jobcompat
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/jobcompat.rb

@@ -4,6 +4,7 @@ require_relative "jobcompat/canonical_worker_name"
 require_relative "jobcompat/config"
 require_relative "jobcompat/git_repository"
 require_relative "jobcompat/analysis"
+require_relative "jobcompat/explanation"
 require_relative "jobcompat/engine"
 require_relative "jobcompat/formatter"
 require_relative "jobcompat/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jobcompat
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - jobcompat contributors
@@ -44,6 +44,7 @@ files:
 - docs/competitive-analysis.md
 - docs/implementation-plan-v0.2.1.md
 - docs/implementation-plan-v0.2.md
+- docs/implementation-plan-v0.3.1.md
 - docs/implementation-plan-v0.3.md
 - docs/implementation-plan.md
 - docs/release-checklist-v0.1.0.md
@@ -57,6 +58,7 @@ files:
 - docs/spec-v0.1.md
 - docs/spec-v0.2.1.md
 - docs/spec-v0.2.md
+- docs/spec-v0.3.1.md
 - docs/spec-v0.3.md
 - exe/jobcompat
 - lib/jobcompat.rb
@@ -67,6 +69,7 @@ files:
 - lib/jobcompat/config.rb
 - lib/jobcompat/engine.rb
 - lib/jobcompat/errors.rb
+- lib/jobcompat/explanation.rb
 - lib/jobcompat/formatter.rb
 - lib/jobcompat/git_repository.rb
 - lib/jobcompat/version.rb