deployangel 0.1.43 → 0.1.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce8544c5aa3368fc5df3c437726bcb157edec54cfa43b90814c3ae0b4e5777dc
-  data.tar.gz: c2cd5fec697b3fc987043ab6aaaf361d34050cd4979ee397dfcf452b3b94dcf4
+  metadata.gz: 6808537b2a27128d5b5c8770015db33cdf62b708776649485f2113ecd5a013d9
+  data.tar.gz: 001e46db33f806a94016b93f6af3dfa7b5709eb923f4918197d6ba2d444120ad
 SHA512:
-  metadata.gz: 0ca495f1e92256a66a96e5b020baaeb75680904be1a89407ba9250e1396f64c3d9441b02b6b59968e3c453c827c4cf76f5850ae405a084ed3567c6ce776e9d82
-  data.tar.gz: 0e6ff274dbf1cf28bea67fbc6ab46f13009ebeef1b3d9a7967ceaa874363ec195f99ee3e2144423107594f10a256fd6483c916d3ed65155a1e0fee8427928683
+  metadata.gz: d08170a8aeb9620b47db7630b95e016c415c11afb04a6c7bc7ea79cac1703e7c1a34c86dddcf73c8385cb258e31f39ca651f3e1339068df544248f507533c9e5
+  data.tar.gz: cdf1c1fe799b63e653abe0309332798d90607d6a3631527acb74669a8689897662870627062e95bd466ed3c70959e28bbe8c87cc8f81a4984f7c458d5726af6a

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.44 (2026-11-14)
+
+- `deployangel context <files>` and the MCP server's `get_production_context`
+  say what production does with code before you change it: the routes and
+  jobs the files serve, how often production ran them in the last week and
+  how many failed, whether a release's clearance would cover a change to them
+  at this time of day, their schedules and critical flows, and failed
+  releases and late regressions on them in the last 90 days. Files it can't
+  map are listed as unmapped, never as unused. The MCP server's instructions,
+  and the block `deployangel install agents` writes, tell coding agents to
+  call it before changing code that serves requests or runs as a job
+  (servers from 2026-11-14).
+
 ## 0.1.43 (2026-11-05)
 
 - The MCP server's instructions, and the block `deployangel install agents`

data/README.md

@@ -517,6 +517,7 @@ bundle exec deployangel exercise --url=https://example.com  # send the plan's re
 bundle exec deployangel release --commit=$SHA          # register a deploy (manual or CI)
 bundle exec deployangel check --name="smoke: signup" --status=pass --covers=registration
 bundle exec deployangel exception <fingerprint>
+bundle exec deployangel context app/jobs/refund_job.rb # what production does with code, before changing it
 bundle exec deployangel doctor                         # check the setup
 ```
 
@@ -580,8 +581,23 @@ server needs `DEPLOYANGEL_API_TOKEN` in the environment it starts in.
 
 Tools: `get_verification`, `wait_for_verification` (up to 5 minutes per call),
 `get_exercise_plan`, `list_deployments`, `get_exception`,
-`list_late_regressions`, and `register_deployment` when the token allows it.
-The tools are read-only with respect to production.
+`list_late_regressions`, `get_production_context`, and `register_deployment`
+when the token allows it. The tools are read-only with respect to production.
+
+### Before changing code
+
+`deployangel context <files>` (or the `get_production_context` MCP tool)
+says what production does with code before you or your agent change it: the
+routes and jobs the files serve, how often production ran them in the last
+week and how many failed, whether a release's clearance would cover a
+change to them at this time of day, their schedules and critical flows, and
+failed releases and late regressions on them in the last 90 days. A rarely
+used route won't be covered by a clearance, so that's when to plan a smoke
+test or `deployangel exercise`. Files map through the routes and jobs the
+agent reported and through stack traces; models and libraries often map
+only through the exceptions raised in them, and a file DeployAngel can't map
+is listed as unmapped, never as unused. Pass `--route` or `--job` to ask
+about a route or job class by name.
 
 ### Clearing quiet releases sooner
 

data/lib/deployangel/cli/formatter.rb

@@ -229,6 +229,40 @@ module DeployAngel
         end
       end
 
+      OUTLOOKS = { "normal_traffic" => "normal traffic covers it", "later_today" => "runs later today",
+                   "rarely_used" => "rarely used: a clearance won't cover it", "unknown" => "outlook unknown" }.freeze
+
+      # Production context, one block per route or job.
+      def production_context(details)
+        lines = []
+        Array(details["items"]).each do |item|
+          uses = "#{item["uses_last_7_days"]} #{item["kind"] == "route" ? "requests" : "runs"} in 7 days"
+          failures = item["failures_last_7_days"].to_i.positive? ? ", #{item["failures_last_7_days"]} failed" : ""
+          lines << "#{item["kind"] == "route" ? "Route" : "Job"} #{item["key"]}: #{uses}#{failures} · " \
+                   "#{OUTLOOKS.fetch(item.dig("clearance", "outlook"), item.dig("clearance", "outlook"))}"
+          lines << "  #{item.dig("clearance", "note")}" if item.dig("clearance", "outlook") != "normal_traffic"
+          lines << "  Pending first use since an earlier release" if item["pending_first_use"]
+          if (schedule = item["schedule"])
+            lines << "  Scheduled #{schedule["schedule"]}#{", next #{schedule["next_at"]}" if schedule["next_at"]} (#{schedule["status"]})"
+          end
+          lines << "  Critical flows: #{item["critical_flows"].join(", ")}" if Array(item["critical_flows"]).any?
+          Array(item["failed_releases"]).each { |failed| lines << "  Failed #{failed["release"]}: #{failed["label"]}" }
+          Array(item["late_regressions"]).each do |late|
+            lines << "  Late regression in #{late["release"]}#{" (dismissed)" if late["dismissed"]}: #{late["summary"]}"
+          end
+        end
+        Array(details["files"]).each do |file|
+          Array(file["exceptions"]).each do |exception|
+            lines << "#{file["path"]}: #{exception["exception_class"]} in #{exception["top_frame"]}, " \
+                     "#{exception["occurrences_last_7_days"]} in 7 days (fingerprint #{exception["fingerprint"]})"
+          end
+        end
+        unmapped = Array(details["unmapped_files"])
+        lines << "Unmapped (not known to be unused): #{unmapped.join(", ")}" if unmapped.any?
+        lines << "Nothing found for these." if lines.empty?
+        (lines + Array(details["notes"]).map { |note| "Note: #{note}" }).join("\n")
+      end
+
       def exception(details)
         [ "#{details["exception_class"]}: #{details["message"]}",
           "Fingerprint #{details["fingerprint"]} · first seen #{details["first_seen_at"]} (#{details["first_seen_release"]})",

data/lib/deployangel/cli.rb

@@ -20,7 +20,7 @@ module DeployAngel
   # Runs without booting Rails.
   class CLI
     USAGE_ERROR = 5
-    COMMANDS = %w[release verify status plan exercise exception check install doctor setup token mcp version help].freeze
+    COMMANDS = %w[release verify status plan exercise exception context check install doctor setup token mcp version help].freeze
 
     HELP = <<~TEXT
       Usage: deployangel <command> [options]
@@ -37,6 +37,8 @@ module DeployAngel
                    requests to production        [--param=NAME=VALUE] [--header="Name: value"]
                                                  [--max-requests=200] [--dry-run]
         exception  Details for a fingerprint     deployangel exception FINGERPRINT
+        context    What production does with      deployangel context FILE... [--route="POST /x"] [--job=Job]
+                   code, before you change it    [--format=text|json]
         check      Report a smoke test result    --name=NAME --status=pass|fail [--covers=a,b]
                                                  [--commit=SHA | --deployment=ID] [--details-url=URL]
         install    Add a Kamal deploy hook,       deployangel install kamal
@@ -136,6 +138,12 @@ module DeployAngel
         and `list_late_regressions` (or run `bundle exec deployangel status`). If a
         recent release failed, isn't cleared yet, or has a late regression, mention
         it before other work.
+      - Before changing code that serves requests or runs as a job: call
+        `get_production_context` with the files you plan to change (or run
+        `bundle exec deployangel context <files>`). If an item's clearance outlook
+        is `rarely_used` or `later_today`, a clearance won't cover your change soon
+        after deploying: say so, and plan to exercise it or report a check that
+        covers it. Files in `unmapped_files` aren't known to be unused.
       #{AGENTS_END}
     MARKDOWN
 
@@ -185,6 +193,7 @@ module DeployAngel
       when "plan" then plan
       when "exercise" then exercise
       when "exception" then exception
+      when "context" then context
       when "check" then check
       when "install" then install
       when "doctor" then doctor
@@ -384,6 +393,28 @@ module DeployAngel
         0
       end
 
+      # What production does with some code, before changing it (spec §27,
+      # Production context).
+      def context
+        options = parse(routes: [], job_classes: [], format: nil) do |o, opts|
+          o.on("--route=ROUTE") { |v| opts[:routes] << v }
+          o.on("--job=JOB_CLASS") { |v| opts[:job_classes] << v }
+          o.on("--format=FORMAT", %w[text json]) { |v| opts[:format] = v }
+        end
+        files = @argv.dup
+        @argv.clear
+        if files.empty? && options[:routes].empty? && options[:job_classes].empty?
+          return usage_error("context needs files, --route, or --job, like `deployangel context app/jobs/refund_job.rb`")
+        end
+
+        details = client.production_context(files: files, routes: options[:routes], job_classes: options[:job_classes])
+        output(details, options[:format]) { Formatter.production_context(details) }
+        0
+      rescue Client::NotFound
+        @stderr.puts("deployangel: this DeployAngel server doesn't offer production context yet")
+        USAGE_ERROR
+      end
+
       def check
         options = parse(name: nil, status: nil, covers: [], details_url: nil) do |o, opts|
           o.on("--name=NAME") { |v| opts[:name] = v }

data/lib/deployangel/client.rb

@@ -40,6 +40,13 @@ module DeployAngel
     def exception(fingerprint) = get("/api/v1/exceptions/#{URI.encode_www_form_component(fingerprint)}")
     def late_regressions(**filters) = get("/api/v1/late_regressions", filters.compact)["late_regressions"]
 
+    # What production does with some code, before a coding agent changes it
+    # (spec §27, Production context).
+    def production_context(files: [], routes: [], job_classes: [])
+      get("/api/v1/production_context",
+        { "files[]" => files, "routes[]" => routes, "job_classes[]" => job_classes }.reject { |_, values| values.empty? })
+    end
+
     def verification(deployment_id, all_findings: false)
       get("/api/v1/deployments/#{deployment_id}/verification", all_findings ? { findings: "all" } : {})
     end

data/lib/deployangel/mcp.rb

@@ -37,6 +37,11 @@ module DeployAngel
         evidence, and give them the accept_url so a person decides. Until someone accepts it, the release
         is failed: never report it as success. A finding with status
         accepted was accepted as intended by the person in accepted_as_intended.
+        Before changing code that serves requests or runs as a job, call get_production_context with the files
+        you plan to change. It says which routes and jobs they serve and how often production runs them. If an
+        item's clearance outlook is rarely_used or later_today, a clearance won't cover your change soon after
+        deploying: tell the user, and plan to exercise it or report a check that covers it. unmapped_files are
+        files DeployAngel can't map to routes or jobs: never take that to mean they're unused.
       TEXT
 
       TARGET_PROPERTIES = {
@@ -128,7 +133,16 @@ module DeployAngel
           tool("list_late_regressions", "Failures found after a release was cleared, on paths the clearance did not cover. " \
                "One with dismissed set was dismissed by a person as a false alarm, with their reason: it needs no action.",
             { "since" => { "type" => "string", "description" => "ISO 8601 time" },
-              "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 50, "default" => 10 } })
+              "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 50, "default" => 10 } }),
+          tool("get_production_context", "What production does with code before you change it: the routes and jobs the given " \
+            "files serve, how often production ran them in the last 7 days and how many failed, whether a release's clearance " \
+            "would cover a change to them (clearance.outlook: normal_traffic, later_today, rarely_used, or unknown), their " \
+            "schedules and critical flows, and failed releases and late regressions on them in the last 90 days. " \
+            "Files it can't map are listed in unmapped_files; that doesn't mean they're unused.",
+            { "files" => { "type" => "array", "items" => { "type" => "string" },
+                           "description" => "Repository-relative paths, e.g. app/jobs/refund_job.rb (up to 50)." },
+              "routes" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Route keys, e.g. \"POST /refunds\"." },
+              "job_classes" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Job class names, e.g. RefundJob." } })
         ]
         if scopes.include?("deployments")
           list << tool("register_deployment", "Register a deployment so it is verified (manual and CI deploys).",
@@ -161,6 +175,7 @@ module DeployAngel
             when "get_exception" then @client.exception(arguments.fetch("fingerprint") { raise ArgumentError, "fingerprint is required" })
             when "list_late_regressions"
               { "late_regressions" => @client.late_regressions(since: arguments["since"], limit: arguments.fetch("limit", 10)) }
+            when "get_production_context" then production_context(arguments)
             when "register_deployment"
               raise ArgumentError, "register_deployment is not available for this token" unless scopes.include?("deployments")
 
@@ -188,6 +203,15 @@ module DeployAngel
             "in_progress" => outcome.exit_code == VerificationWaiter::TIMED_OUT, "verification" => outcome.document }
         end
 
+        def production_context(arguments)
+          files, routes, job_classes = %w[files routes job_classes].map { |key| Array(arguments[key]).map(&:to_s).reject(&:empty?) }
+          raise ArgumentError, "give files, routes, or job_classes" if [ files, routes, job_classes ].all?(&:empty?)
+
+          @client.production_context(files: files, routes: routes, job_classes: job_classes)
+        rescue Client::NotFound
+          { "note" => "This DeployAngel server doesn't offer production context yet." }
+        end
+
         def plan_content(outcome)
           return { "found" => false, "note" => "No matching deployment is registered yet." } if outcome.not_found
 

data/lib/deployangel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeployAngel
-  VERSION = "0.1.43"
+  VERSION = "0.1.44"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.43
+  version: 0.1.44
 platform: ruby
 authors:
 - Jordan Owens