asgard 0.3.1 → 0.3.2

data/docs/dependencies.md

@@ -145,9 +145,54 @@ When `asgard ci` runs, `setup` executes once even though both `test` and `lint`
 
 ---
 
+## Transitive Dependencies
+
+When a dependency has its own dependencies, Asgard resolves them recursively before running the dependent task. The deduplication set ensures each task runs at most once regardless of how many paths lead to it.
+
+Consider this graph:
+
+```ruby
+class Tasks
+  desc "Fetch gems"
+  def setup = sh "bundle install"
+
+  depends_on :setup
+  desc "Compile assets"
+  def build = sh "rake assets:precompile"
+
+  desc "Check code style"
+  def lint = sh "bundle exec rubocop"
+
+  depends_on :build, :lint, :setup
+  desc "Run the full pipeline"
+  def ci = puts "Done."
+end
+```
+
+`ci` declares three sequential dependencies: `build`, `lint`, `setup`. But `build` itself depends on `setup`. The effective execution order is:
+
+```
+setup          ← run as build's prerequisite
+  ↓
+build
+  ↓
+lint
+  ↓
+(setup skipped — already done)
+  ↓
+ci
+```
+
+`setup` runs once — on its first encounter as `build`'s prerequisite. When `ci`'s own stage for `setup` is reached, the deduplication set skips it.
+
+!!! tip
+    When a task is both a transitive dependency and a direct dependency, declare it only where it logically belongs — as a prerequisite of the task that needs it. Declaring it redundantly at the top level is harmless (deduplication handles it) but adds noise.
+
+---
+
 ## Circular Dependency Detection
 
-Asgard validates the full dependency graph using [Dagwood](https://rubygems.org/gems/dagwood) before any task runs. A circular dependency produces a clean error and exits:
+Asgard validates the full dependency graph using stdlib [TSort](https://docs.ruby-lang.org/en/master/TSort.html) before any task runs. A circular dependency produces a clean error and exits:
 
 ```ruby
 class Tasks
@@ -187,7 +232,43 @@ class Tasks
 end
 ```
 
-When `--auto-load` is used, `*.loki` files are loaded alphabetically, so `build.loki` loads before `test.loki`. If you need to control load order, use explicit `require_relative` from `.loki`.
+Because `*.loki` files are loaded alphabetically when `import "*.loki"` is used, `build.loki` loads before `test.loki`. If you need to control load order precisely, use explicit `import` calls with full filenames rather than a glob.
+
+---
+
+## Dynamic Dependencies (Proc Form)
+
+`depends_on` normally takes a fixed list, recorded the moment the `def` right after it is encountered — which is why load order matters, as above. Pass a `Proc` or lambda instead, and that list is computed *later*, after every `.loki` file has finished loading, rather than at the point `depends_on` itself is evaluated:
+
+```ruby
+depends_on -> { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+desc "Run every *_check quality gate task in parallel"
+def quality
+  # ...
+end
+```
+
+This solves exactly the "load order matters" problem from the previous section: a plain array can only name tasks that already exist in `.loki` files loaded *before* this one. A Proc is resolved once every file has loaded, so it can safely reference a task defined in a file that hasn't been imported yet at the point `depends_on` is written — including one that only exists conditionally, e.g. a Rails-specific task file imported with `import "quality_rails.loki" if defined?(Rails)`.
+
+**Shape:** the Proc must return exactly what the plain-array form would receive as its splat arguments — an array of stages, each a `Symbol` (sequential) or `Array` (parallel group). The example above returns `[[:a_check, :b_check, :c_check]]`: one stage, containing every matching task, all running in parallel — the same shape as `depends_on [:a_check, :b_check, :c_check]`.
+
+**When it runs:** once, when `validate_deps!` runs (right after the `.loki` chain finishes loading, before any task dispatches). The resolved result replaces the Proc in the dependency table, so cycle detection, undefined-task checks, and arity checks all run against the *resolved* list — a Proc that references an undefined task, or that itself introduces a cycle, is caught at startup exactly like a plain array would be:
+
+```bash
+asgard quality
+# asgard: undefined task(s) in depends_on: ghost_check
+```
+
+**`self` inside the Proc:** since the Proc is written directly in a `class Tasks` body, it lexically captures that class as `self` — so it can call `all_commands`, `_deps`, or any other class-level method bare, without a `self.class.` prefix, even though it's actually invoked later from inside `validate_deps!`.
+
+**If the Proc raises**, the error is caught and re-raised as `Asgard::Error` naming the task it was declared for:
+
+```
+asgard: depends_on proc for 'quality' raised RuntimeError: boom
+```
+
+!!! tip
+    Reach for this only when the dependency list genuinely can't be known until every file has loaded — like "every task whose name ends in `_check`," discovered across several `.loki` files. For a fixed, known-upfront list, the plain array form is simpler and reads just as clearly.
 
 ---
 

data/docs/getting-started.md

@@ -138,24 +138,26 @@ myproject/
   qa.loki        ← test and lint tasks
 ```
 
-Each `*.loki` file reopens `class Tasks`. To load them, pass `--auto-load` to the `asgard` command — they are loaded alphabetically before `.loki`. See [Task Files](task-files.md) for full details.
+Each `*.loki` file reopens `class Tasks`. To load them, call `import "*.loki"` at the top of `.loki` — files are loaded in alphabetical order. See [Task Files](task-files.md) for full details.
 
 ---
 
 ## Built-in Flags
 
-Every task automatically has three flags available, defined as `class_option` on `Tasks`:
+Every task automatically has four flags available, defined as `class_option` on `Tasks`:
 
 | Flag | Description |
 |---|---|
 | `--version` | Print the Asgard version and exit |
 | `--debug` | Set `$DEBUG = true` before the task runs |
 | `--verbose` | Set `$VERBOSE = true` before the task runs |
+| `--doctor` | Diagnose `.loki` resolution, imports, and task definitions for the CWD, then exit |
 
 ```bash
 asgard --version
 asgard hello --debug
 asgard hello --verbose
+asgard --doctor
 ```
 
 Inside a task body, use the `debug?` and `verbose?` predicates:

data/docs/index.md

@@ -18,7 +18,7 @@
 <li><strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code></li>
 <li><strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories</li>
 <li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files loaded via <code>import</code></li>
-<li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, and <code>--verbose</code> available on every task</li>
+<li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, <code>--verbose</code>, and <code>--doctor</code> available on every task</li>
 </ul>
 </td>
 </tr>
@@ -72,7 +72,7 @@ The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_d
 | [Subcommands](subcommands.md) | Grouping tasks under a namespace |
 | [Shell Helpers](shell.md) | `sh`, `shebang`, and supported interpreters |
 | [Environment](environment.md) | Loading `.env` files with `dotenv` |
-| [Task Files](task-files.md) | `.loki` root marker, `--auto-load`, multi-file layout |
+| [Task Files](task-files.md) | `.loki` root marker, `import`, multi-file layout |
 | [API Reference](api.md) | Module methods, DSL methods, error classes |
 | [Examples](examples.md) | Working `.loki` files for every feature |
 | [Changelog](changelog.md) | Release history |
@@ -82,4 +82,4 @@ The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_d
 ## Requirements
 
 - Ruby >= 3.2.0
-- Dependencies: [thor](https://github.com/rails/thor) `~> 1.0`, [dagwood](https://rubygems.org/gems/dagwood) `~> 1.0`, [dotenv](https://github.com/bkeepers/dotenv) `~> 3.0`
+- Dependencies: [thor](https://github.com/rails/thor) `~> 1.0`, [dotenv](https://github.com/bkeepers/dotenv) `~> 3.0`

data/docs/options.md

@@ -1,6 +1,6 @@
 # Options & Flags
 
-Asgard tasks use the full Thor option system. Options declared with `method_option` (alias: `option`) apply to a single task. Options declared with `class_option` apply to every task in the class. Asgard ships with three built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, and `--version`.
+Asgard tasks use the full Thor option system. Options declared with `method_option` (alias: `option`) apply to a single task. Options declared with `class_option` apply to every task in the class. Asgard ships with four built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, `--version`, and `--doctor`.
 
 ---
 
@@ -80,7 +80,7 @@ class Tasks
   class_option :color,
                type:    :boolean,
                default: true,
-               desc:    "Colorise output"
+               desc:    "Colorize output"
   no_negate :color
 end
 ```
@@ -88,13 +88,13 @@ end
 Help output before `no_negate`:
 
 ```
-[--color], [--no-color], [--skip-color]  # Colorise output
+[--color], [--no-color], [--skip-color]  # Colorize output
 ```
 
 Help output after `no_negate`:
 
 ```
-[--color]                                # Colorise output
+[--color]                                # Colorize output
 ```
 
 `no_negate` accepts multiple option names in a single call:
@@ -109,7 +109,7 @@ It has no effect on runtime behaviour — `--no-color` still works on the CLI; o
 
 ## Built-in Flags
 
-`Tasks` ships with three built-in `class_option` declarations — `--debug`, `--verbose`, and `--version` — all visible in the Options section of `asgard help`.
+`Tasks` ships with four built-in `class_option` declarations — `--debug`, `--verbose`, `--version`, and `--doctor` — all visible in the Options section of `asgard help`.
 
 ### `--version`
 
@@ -120,6 +120,16 @@ asgard --version
 # 0.3.0
 ```
 
+### `--doctor`
+
+A `class_option :doctor` of type `:boolean`. Diagnoses `.loki` resolution, import chains, and task definitions for the current directory, then exits. Handled by `Asgard.run!` before the `.loki` file is loaded (same pattern as `--version`) — deliberately so, since it needs to keep working in the exact situations that would otherwise abort `run!`: a broken `.loki` file, a circular or undefined dependency, or a task silently redefined by a later `def`. The report includes a "Tasks by file" listing — every command grouped by the file it's defined in, as `file:line` — with any silently-overridden task called out inline, right where it's defined. `no_negate :doctor` suppresses the `[--no-doctor]` / `[--skip-doctor]` variants:
+
+```bash
+asgard --doctor
+```
+
+See [`Asgard::Doctor` in the API Reference](api.md#asgarddoctor) for the full breakdown of what it checks.
+
 ### `--debug`
 
 A `class_option :debug` of type `:boolean`. When passed, sets `$DEBUG = true` before the task body runs (via the `invoke_command` hook in `Asgard::Base`):
@@ -211,4 +221,4 @@ asgard _something
 # asgard: unknown command '_something'
 ```
 
-If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being blocked. Built-in `class_option` declarations (like `--version`, `--debug`, `--verbose`) do not use the `_` prefix because they are options, not commands.
+If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being blocked. Built-in `class_option` declarations (like `--version`, `--debug`, `--verbose`, `--doctor`) do not use the `_` prefix because they are options, not commands.

data/examples/bad.loki

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# Demonstrates review.md Critical Issue #1: parallel depends_on tasks that
+# write to shared instance state on `self` race each other.
+#
+# quality.loki's *_check tasks each write a *different* named ivar
+# (@test_result, @rubocop_result, ...), so MRI's GVL happens to hide the
+# race in practice — every write lands on a distinct slot. This file
+# isolates the actual hazard by having 4 parallel workers read-modify-write
+# the SAME @hits counter, the way any real *_check task would if it
+# accumulated into one shared results structure instead of one ivar each.
+#
+# `@hits = @hits + 1` is not one atomic operation — it's a read, an add,
+# then a write — and MRI can switch threads between those steps. Thread.pass
+# inside the loop forces exactly those switches, so the lost-update race
+# shows up reliably instead of "most of the time."
+#
+# Run with:
+#   asgard bad_race
+#
+# Expected @hits: 4000 (4 workers x 1000 increments each)
+# Actual: consistently lower — proof of the lost-update race described in
+# review.md item #1.
+
+BAD_RACE_WORKERS = 4
+BAD_RACE_REPS    = 1000
+
+class Tasks
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_1 = bump_shared_counter
+
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_2 = bump_shared_counter
+
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_3 = bump_shared_counter
+
+  desc "Increment the shared @hits counter, unsynchronized (worker)"
+  def racer_4 = bump_shared_counter
+
+  depends_on [:racer_1, :racer_2, :racer_3, :racer_4]
+  desc "Show the lost-update race in @hits"
+  def bad_race
+    expected = BAD_RACE_WORKERS * BAD_RACE_REPS
+    puts "expected @hits == #{expected}, got #{@hits}"
+
+    if @hits == expected
+      puts "no corruption this run — the race is timing-dependent, rerun a few times"
+    else
+      puts "DATA RACE CONFIRMED: #{expected - @hits} update(s) lost"
+    end
+  end
+
+  no_commands do
+    def bump_shared_counter
+      @hits ||= 0
+      BAD_RACE_REPS.times do
+        current = @hits    # read
+        Thread.pass        # force a context switch before the write lands
+        @hits = current + 1 # write — another thread's read may already be stale
+      end
+    end
+  end
+end

data/gem_tasks.loki

@@ -2,6 +2,15 @@
 # Gem lifecycle tasks — imported by .loki
 
 class Tasks
+  desc "Open IRB console with the gem loaded"
+  def console
+    if File.exist?("bin/console")
+      sh "bin/console"
+    else
+      sh "bundle exec irb -Ilib -r #{@@project}"
+    end
+  end
+
   desc "Build the gem package"
   depends_on :quality
   def build
@@ -16,12 +25,19 @@ class Tasks
     sh "gem install pkg/asgard-#{project_version}.gem"
   end
 
-  desc "Release to RubyGems"
+  desc "release", "Release gem to RubyGems (runs quality gate first)"
+  option :yes, aliases: "-y", type: :boolean, default: false, desc: "Skip confirmation prompt"
   depends_on :quality
   def release
     tag      = "v#{project_version}"
     gem_file = "pkg/asgard-#{project_version}.gem"
 
+    unless options[:yes]
+      print "Release #{@@project} v#{project_version} to RubyGems? [y/N] "
+      $stdout.flush
+      return puts "Aborted." unless $stdin.gets.strip.downcase == "y"
+    end
+
     abort "Working directory is not clean — commit or stash changes first." unless `git status --porcelain`.strip.empty?
     abort "Tag #{tag} already exists." unless `git tag -l #{tag}`.strip.empty?
 

data/git.loki

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# Per-repo git tasks — imported by .loki
+
+class Tasks
+  desc "Push the current branch to its remote"
+  def push = sh "git push"
+
+  desc "Pull (fast-forward only) from the remote"
+  def pull = sh "git pull --ff-only"
+
+  desc "Fetch from the remote"
+  def fetch = sh "git fetch"
+end

data/lib/asgard/base/dependency_graph.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Dependency declaration (`depends_on`) and full-graph validation
+    # (`validate_deps!`), backed by stdlib TSort for cycle detection.
+    module DependencyGraph
+      def _deps
+        @_deps ||= {}
+      end
+
+      # Declare dependencies for the next task.
+      # Bare symbols run sequentially; arrays within the splat run in parallel.
+      #
+      #   depends_on :build                          # sequential
+      #   depends_on :build, :lint                   # both sequential
+      #   depends_on [:build, :lint]                 # build and lint in parallel
+      #   depends_on :setup, [:build, :lint], :test  # setup, then build+lint, then test
+      #
+      # A sole Proc/lambda defers resolution to validate_deps! (after every
+      # .loki file has loaded), instead of now. It must return the same shape
+      # the splat form above would: an array of stages, each a Symbol
+      # (sequential) or Array (parallel group).
+      #
+      #   depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+      def depends_on(*tasks)
+        @_pending_deps = tasks
+      end
+
+      # Validate the full dep graph for cycles using stdlib TSort.
+      def validate_deps!
+        _check_orphaned_deps!
+        return if _deps.empty?
+
+        _resolve_lazy_deps!
+        all_task_names = all_commands.keys.map(&:to_sym)
+        _check_undefined_deps!(all_task_names)
+        _check_dep_arities!
+        _build_and_sort_graph(all_task_names)
+      rescue TSort::Cyclic => e
+        raise Asgard::CircularDependencyError, e.message
+      end
+
+      private
+
+      # Normalizes depends_on's raw splat args into a _deps-ready value: the
+      # sole Proc/lambda unresolved (see #depends_on), or a concrete stage
+      # array.
+      def _normalize_pending_deps(pending)
+        sole = pending.first
+        return sole if pending.size == 1 && sole.respond_to?(:call)
+
+        _stages_from(pending)
+      end
+
+      # Each element is a Symbol (sequential) or Array (parallel group).
+      def _stages_from(list)
+        list.map { |d| Array(d).map(&:to_sym) }
+      end
+
+      # Replaces any Proc-valued _deps entry (see #depends_on) with its
+      # resolved stage array. Runs once, after the full .loki chain has
+      # loaded, so the Proc can safely reference tasks defined in any file.
+      def _resolve_lazy_deps!
+        _deps.each do |task, stages_or_proc|
+          next unless stages_or_proc.respond_to?(:call)
+
+          _deps[task] = _stages_from(Array(_call_dep_proc(task, stages_or_proc)))
+        end
+      end
+
+      def _call_dep_proc(task, dep_proc)
+        dep_proc.call
+      rescue StandardError => e
+        raise Asgard::Error, "depends_on proc for '#{task}' raised #{e.class}: #{e.message}"
+      end
+
+      def _check_orphaned_deps!
+        pending = Array(@_pending_deps)
+        return unless pending.any?
+
+        raise Asgard::Error,
+              "depends_on(#{pending.join(', ')}) declared without a following task definition"
+      end
+
+      def _check_undefined_deps!(all_task_names)
+        undefined = _deps.values.flatten.uniq - all_task_names
+        return unless undefined.any?
+
+        raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
+      end
+
+      def _check_dep_arities!
+        _deps.each_value do |stages|
+          stages.flatten.each do |dep|
+            meth = instance_method(dep.to_s)
+            required = meth.parameters.count { |type, _| type == :req }
+            next unless required.positive?
+
+            raise Asgard::Error,
+                  "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
+          end
+        end
+      end
+
+      # Runs a full topological sort purely to raise TSort::Cyclic on a cycle;
+      # the order itself isn't otherwise used (execution order comes from the
+      # stage groups each task's own depends_on declared).
+      def _build_and_sort_graph(all_task_names)
+        full_graph = all_task_names.to_h { |task| [task, _deps.fetch(task, []).flatten] }
+        Graph.new(full_graph).tsort
+      end
+
+      # Minimal TSort-able wrapper around a task => dependency-list Hash.
+      Graph = Struct.new(:edges) do
+        include TSort
+
+        def tsort_each_node(&) = edges.each_key(&)
+        def tsort_each_child(node, &) = edges.fetch(node).each(&)
+      end
+      private_constant :Graph
+    end
+  end
+end

data/lib/asgard/base/dispatch.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Task execution engine: resolves and runs declared dependencies (in
+    # parallel where declared) before the target command runs.
+    #
+    # Completion-based deduplication: a task is only marked done after its
+    # body finishes. Threads that arrive at an already-running shared dep
+    # wait on its ConditionVariable rather than proceeding immediately,
+    # preventing the race where parallel tasks start before a shared dep
+    # has actually completed.
+    module Dispatch
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def _running
+          @_running ||= Set.new
+        end
+
+        def _done
+          @_done ||= Set.new
+        end
+
+        def _cond
+          @_cond ||= Hash.new { |h, k| h[k] = ConditionVariable.new }
+        end
+
+        # Completed tasks' return values, keyed by task name — lets a task
+        # already run by one thread hand its result to another thread that
+        # shares the dependency, without either touching `self`.
+        def _results
+          @_results ||= {}
+        end
+
+        def _ran_mutex
+          @_ran_mutex ||= Mutex.new
+        end
+
+        # Reset execution tracking for a fresh asgard invocation.
+        def _reset_ran!
+          _ran_mutex.synchronize do
+            @_running = Set.new
+            @_done    = Set.new
+            @_cond    = Hash.new { |h, k| h[k] = ConditionVariable.new }
+            @_results = {}
+          end
+        end
+      end
+
+      # Dispatch hook: resolves and runs all deps (in parallel where declared)
+      # before executing the target command.
+      def invoke_command(command, *)
+        $DEBUG   = true if options[:debug]
+        $VERBOSE = true if options[:verbose]
+        target = command.name.to_sym
+        return cached_result(target) unless acquire_run_token(target)
+
+        result = nil
+        begin
+          resolved_deps = run_deps_for(target)
+          result = with_dep_results(resolved_deps) { command.run(self, *) }
+        ensure
+          signal_done(target, result)
+        end
+        result
+      end
+
+      # The results of +target+'s direct dependencies, keyed by task name —
+      # available to a task body while it runs, e.g. `dep_result(:test_check)`.
+      def dep_results
+        Thread.current[:asgard_dep_results] || {}
+      end
+
+      def dep_result(task)
+        dep_results[task.to_sym]
+      end
+
+      private
+
+      def with_dep_results(results)
+        thread   = Thread.current
+        previous = thread[:asgard_dep_results]
+        thread[:asgard_dep_results] = results
+        yield
+      ensure
+        thread[:asgard_dep_results] = previous
+      end
+
+      def cached_result(target)
+        klass = self.class
+        klass._ran_mutex.synchronize { klass._results[target] }
+      end
+
+      def acquire_run_token(target)
+        klass   = self.class
+        mutex   = klass._ran_mutex
+        done    = klass._done
+        running = klass._running
+
+        mutex.synchronize do
+          if done.include?(target)
+            false
+          elsif running.include?(target)
+            klass._cond[target].wait(mutex) until done.include?(target)
+            false
+          else
+            running.add(target)
+            true
+          end
+        end
+      end
+
+      def run_deps_for(target)
+        stages = self.class._deps[target]
+        return {} unless stages&.any?
+
+        stages.each_with_object({}) { |group, acc| acc.merge!(run_dep_group(group)) }
+      end
+
+      def run_dep_group(group)
+        return { group.first => run_dep(group.first) } unless group.size > 1
+
+        threads = group.map { |task| [task, Thread.new { run_dep(task) }] }
+        errors  = []
+        results = {}
+        threads.each do |task, t|
+          results[task] = t.value
+        rescue => e
+          errors << e
+        end
+
+        if errors.size == 1
+          raise errors.first
+        elsif errors.any?
+          errors.each { |e| warn "asgard: #{e.message}" }
+          raise Asgard::Error, "#{errors.size} parallel dependencies failed"
+        end
+
+        results
+      end
+
+      def signal_done(target, result)
+        klass = self.class
+        klass._ran_mutex.synchronize do
+          klass._done.add(target)
+          klass._results[target] = result
+          klass._cond[target].broadcast
+        end
+      end
+
+      def run_dep(task)
+        command = self.class.all_commands[task.to_s]
+        invoke_command(command) if command
+      end
+    end
+  end
+end

data/lib/asgard/base/registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Asgard
+  class Base < Thor
+    # Tracks every Asgard::Base subclass ever defined, and every method
+    # name's full source_location history — the data Doctor (`asgard
+    # --doctor`) uses to detect a silently-overridden `def`, same file or
+    # across files.
+    module Registry
+      def subclasses
+        @subclasses ||= []
+      end
+
+      def inherited(subclass)
+        super
+        Asgard::Base.subclasses << subclass
+        subclass.instance_variable_set(:@_deps,              {})
+        subclass.instance_variable_set(:@_method_log,        Hash.new { |h, k| h[k] = [] })
+        subclass.instance_variable_set(:@_pending_deps,      [])
+        subclass.instance_variable_set(:@_pending_single_desc,      nil)
+        subclass.instance_variable_set(:@_pending_single_desc_opts, nil)
+        subclass.instance_variable_set(:@_running,    Set.new)
+        subclass.instance_variable_set(:@_done,       Set.new)
+        subclass.instance_variable_set(:@_cond,       Hash.new { |h, k| h[k] = ConditionVariable.new })
+        subclass.instance_variable_set(:@_ran_mutex,  Mutex.new)
+      end
+
+      # Every source_location a method name has ever been defined at, in
+      # definition order — so a later `def` silently overriding an earlier
+      # one (same name, different file) is still visible after the fact.
+      # Doctor is the consumer; asgard itself doesn't otherwise care once
+      # the last definition wins.
+      def _method_log
+        @_method_log ||= Hash.new { |h, k| h[k] = [] }
+      end
+    end
+  end
+end