Raise if a stage has an invalid name like "deploy"

features/stage_failure.feature

@@ -0,0 +1,9 @@
+Feature: Stage failure
+
+  Background:
+    Given a test app with the default configuration
+    And a stage file named deploy.rb
+
+  Scenario: Running a task
+    When I run cap "doctor"
+    Then the task fails

features/step_definitions/setup.rb

@@ -52,3 +52,7 @@ Given(/^a custom task to run in the event of a failure$/) do
   safely_remove_file(TestApp.shared_path.join("failed"))
   TestApp.copy_task_to_test_app("spec/support/tasks/failed.rake")
 end
+
+Given(/^a stage file named (.+)$/) do |filename|
+  TestApp.write_local_stage_file(filename)
+end

lib/capistrano/dsl/stages.rb

@@ -1,8 +1,13 @@
 module Capistrano
   module DSL
     module Stages
+      RESERVED_NAMES = %w(deploy doctor install).freeze
+      private_constant :RESERVED_NAMES
+
       def stages
-        Dir[stage_definitions].map { |f| File.basename(f, ".rb") }
+        names = Dir[stage_definitions].map { |f| File.basename(f, ".rb") }
+        assert_valid_stage_names(names)
+        names
       end
 
       def stage_definitions
@@ -12,6 +17,15 @@ module Capistrano
       def stage_set?
         !!fetch(:stage, false)
       end
+
+      private
+
+      def assert_valid_stage_names(names)
+        invalid = names.find { |n| RESERVED_NAMES.include?(n) }
+        return if invalid.nil?
+
+        raise t("error.invalid_stage_name", name: invalid, path: stage_config_path.join("#{invalid}.rb"))
+      end
     end
   end
 end

lib/capistrano/i18n.rb

@@ -24,6 +24,7 @@ en = {
     bye: "bye"
   },
   error: {
+    invalid_stage_name: '"%{name}" is a reserved word and cannot be used as a stage. Rename "%{path}" to something else.',
     user: {
       does_not_exist: "User %{user} does not exists",
       cannot_switch: "Cannot switch to user %{user}"

spec/support/test_app.rb

@@ -61,6 +61,12 @@ module TestApp
     end
   end
 
+  def write_local_stage_file(filename, config=nil)
+    File.open(test_app_path.join("config/deploy/#{filename}"), "w") do |file|
+      file.write(config) if config
+    end
+  end
+
   def append_to_deploy_file(config)
     File.open(test_stage_path, "a") do |file|
       file.write config + "\n"