asgard 0.1.2 → 0.3.0

data/docs/api.md

@@ -0,0 +1,204 @@
+# API Reference
+
+This page documents the public Ruby API for the Asgard gem. Most users interact with Asgard through the CLI and the task DSL — this page is primarily useful when integrating Asgard into tooling or extending it programmatically.
+
+---
+
+## `Asgard` Module Methods
+
+These class methods are defined on the `Asgard` module itself.
+
+| Method | Signature | Description |
+|---|---|---|
+| `run!` | `Asgard.run!(argv)` | Main entry point. Finds `.loki`, loads all task files, validates the dependency graph, and dispatches via Thor. Handles its own errors: missing `.loki` and circular dependencies both produce a clean one-line message and `exit 1`. |
+| `find_task_file` | `Asgard.find_task_file → String, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns the absolute path string of the first match, or `nil` if none is found. |
+
+### `run!` Details
+
+```ruby
+Asgard.run!(ARGV)
+```
+
+`run!` guards against direct invocation of `_`-prefixed commands before any files are loaded:
+
+```ruby
+abort "asgard: unknown command '#{argv.first}'" if argv.first&.start_with?("_")
+```
+
+After loading task files, it calls `Tasks.validate_deps!` (circular dependency check) and `Tasks._reset_ran!` (clears per-invocation deduplication state) before starting Thor.
+
+---
+
+## Kernel Methods
+
+These methods are defined as `module_function` on `Kernel` and are therefore available everywhere in Ruby — at the top level of `.loki` files, inside class bodies, and inside task method bodies. No `require` or `include` is needed; they are loaded when `asgard` starts.
+
+| Method | Signature | Returns | Description |
+|---|---|---|---|
+| `loki_up` | `loki_up(name = ".loki") → String, nil` | Absolute path or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns the first match's absolute path, or `nil` if not found. Exact filenames only — does not expand globs. |
+| `import` | `import(path) → true, false` | `true` if any file newly loaded | Loads one `.loki` file or a glob of `.loki` files. Relative paths resolve relative to the caller's file (like `require_relative`). Idempotent via `$LOADED_FEATURES`. Raises `ArgumentError` if `path` does not end with `.loki`. Raises `LoadError` if a non-glob path does not exist. |
+| `import_up` | `import_up(name = ".loki") → true, false` | `true` if any file newly loaded | Combines `loki_up` and `import`. Walks ancestors to find the file or glob match, then loads it. Returns `false` if nothing is found. |
+| `debug?` | `debug? → true, false` | `$DEBUG` | Returns the current value of `$DEBUG`. Set to `true` by `--debug` on the CLI or directly via `$DEBUG = true`. |
+| `verbose?` | `verbose? → true, false` | `$VERBOSE` | Returns the current value of `$VERBOSE`. Set to `true` by `--verbose` on the CLI or directly via `$VERBOSE = true`. |
+| `env` | `env(name, default = nil) → String, nil` | `ENV` value or default | Fetches an environment variable by symbol or string name. The name is upcased automatically. Raises `KeyError` when the variable is missing and no default is given. |
+
+### `loki_up` Details
+
+Despite the name, `loki_up` is not limited to `.loki` files — it locates any file by walking up the directory tree:
+
+```ruby
+loki_up                       # find .loki (the project root marker)
+loki_up("gem_tasks.loki")     # find gem_tasks.loki in CWD or any ancestor
+loki_up(".env")               # find the nearest .env file up the tree
+loki_up("VERSION")            # find a VERSION file in CWD or any ancestor
+```
+
+Returns an absolute path string or `nil`. Does not load the file.
+
+```ruby
+if (path = loki_up("gem_tasks.loki"))
+  import path
+end
+
+# Pass the located .env to dotenv — works from any subdirectory
+dotenv loki_up(".env") || ".env"
+```
+
+### `import` Details
+
+```ruby
+import "build.loki"                  # relative — resolved from the calling file's directory
+import "/home/shared/gem_tasks.loki" # absolute
+import "*.loki"                      # all *.loki in the same directory as the caller
+import "../shared/*.loki"            # all *.loki one level up
+import "**/*.loki"                   # all *.loki recursively
+import Pathname.new("tasks.loki")    # Pathname accepted
+```
+
+**Extension requirement:** the path (or glob pattern) must end with `.loki`. Passing any other extension raises `ArgumentError`.
+
+**Glob behaviour:** `Dir.glob` is used for pattern expansion. `*.loki` does not match `.loki` (the dotfile) — Ruby's glob excludes dotfiles from `*` by default. Files are loaded in the order `Dir.glob` returns them (sorted on Ruby ≥ 2.7).
+
+**Idempotency:** each resolved absolute path is checked against `$LOADED_FEATURES` before loading. A file already in `$LOADED_FEATURES` is silently skipped and contributes `false` to the return value.
+
+**Return value:** `true` if at least one file was newly loaded; `false` if all matched files were already loaded or no glob pattern produced any matches.
+
+**Verbose/debug output** (to stderr):
+- `verbose?` true — prints each file path as it is loaded
+- `debug?` true — also prints a skip message for each already-loaded file
+
+### `import_up` Details
+
+```ruby
+import_up                          # find and load .loki
+import_up "gem_tasks.loki"         # find and load gem_tasks.loki up the tree
+import_up "*.loki"                 # find the nearest ancestor with *.loki files and load them all
+```
+
+**Exact name:** delegates to `loki_up` to find the file, then calls `import` with the absolute path. Returns `false` without raising if the file is not found.
+
+**Glob name:** walks ancestor directories manually using `Dir.glob`. Stops at the **first** ancestor that has any matches and loads all of them — it does not continue walking after finding a match. Returns `false` if no ancestor contains matching files.
+
+**Verbose/debug output** (to stderr):
+- `verbose?` true — prints `name → /full/path` when a file or directory is found
+- `debug?` true — also prints `name not found` when the search comes up empty
+
+---
+
+## `Asgard::Base` DSL Class Methods
+
+`Asgard::Base` is a `Thor` subclass that provides the task DSL. It is the superclass of `Tasks`. All DSL methods are class methods (called in the class body).
+
+| Method | Signature | Description |
+|---|---|---|
+| `depends_on` | `depends_on(*tasks)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. |
+| `dotenv` | `dotenv(path = ".env")` | Load the specified `.env` file into `ENV` using the dotenv gem. Silently skipped if the file does not exist. Called at class-load time. |
+| `sh` | `sh(script, silent: false)` | Instance method. Run a shell command or multiline heredoc. Single-line → `system(script)`; multiline → `system("bash", "-c", script)`. Exits with the command's status on failure. |
+| `shebang` | `shebang(interpreter, script, silent: false)` | Instance method. Write `script` to a tempfile and execute it with `interpreter`. See the [Shell Helpers](shell.md) page for the full interpreter table. |
+| `validate_deps!` | `Tasks.validate_deps!` | Build and topologically sort the full dependency graph using Dagwood. Raises `Asgard::CircularDependencyError` on cycles. Called by `run!` at startup. |
+| `_reset_ran!` | `Tasks._reset_ran!` | Clear the per-invocation task deduplication set. Called by `run!` before dispatching. Thread-safe via Mutex. |
+
+### `depends_on` Argument Shapes
+
+```ruby
+depends_on :build                          # single sequential dep
+depends_on :clean, :build                  # two sequential deps
+depends_on [:lint, :typecheck]             # lint and typecheck run in parallel
+depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently, then test
+```
+
+---
+
+## `Tasks` Built-ins
+
+`Tasks` is pre-defined by the gem as `class Tasks < Asgard::Base`. It adds the following:
+
+| Item | Type | Description |
+|---|---|---|
+| `class_option :debug` | class option | `--debug` flag. Sets `$DEBUG = true` before any task runs. Boolean, default `false`. |
+| `class_option :verbose` | class option | `--verbose` flag. Sets `$VERBOSE = true` before any task runs. Boolean, default `false`. |
+| `_version` | private task method | Implements `--version`. Prints `Asgard::VERSION` and exits. Registered via `map "--version" => :_version`. Uses `_` prefix convention. |
+| `debug?` | Kernel module function | Returns `$DEBUG`. Available everywhere via `Kernel`. |
+| `verbose?` | Kernel module function | Returns `$VERBOSE`. Available everywhere via `Kernel`. |
+
+---
+
+## `Asgard::Base` Internal Class Methods
+
+These are implementation details exposed for extensibility. Prefer the DSL methods above in normal use.
+
+| Method | Description |
+|---|---|
+| `_deps` | Hash mapping task name symbols to their stage arrays. Set by `depends_on` + `method_added`. |
+| `_done` | `Set` of task name symbols that have completed in the current invocation. |
+| `_running` | `Set` of task name symbols currently executing (started but not yet finished). |
+| `_cond` | Hash of `ConditionVariable` objects keyed by task name; threads wait here when a dep is in-flight. |
+| `_ran_mutex` | `Mutex` protecting `_done`, `_running`, and `_cond` for thread-safe access. |
+| `_build_dep_graph(stages)` | Translates the stage array (from `_deps`) into a Dagwood-compatible hash. |
+
+---
+
+## `invoke_command` Hook
+
+`Asgard::Base` overrides Thor's `invoke_command` to implement dependency resolution and deduplication:
+
+1. Sets `$DEBUG` / `$VERBOSE` from `options` if the corresponding flags are present.
+2. Tries to acquire a run token (`acquire_run_token`): if the task is already in `_done`, returns immediately (skip); if it is in `_running`, waits on the `_cond` ConditionVariable until it finishes, then returns (skip); otherwise adds the task to `_running` and continues.
+3. Resolves dependency stages from `_deps`, builds the Dagwood graph, and executes groups (parallel groups in threads, sequential groups one at a time).
+4. Calls `command.run(self, *args)` to execute the task itself.
+5. In an `ensure` block, adds the task to `_done` and broadcasts on its `_cond` to wake any waiting threads.
+
+---
+
+## Error Classes
+
+| Class | Superclass | Description |
+|---|---|---|
+| `Asgard::Error` | `StandardError` | Base error class for all Asgard errors. |
+| `Asgard::CircularDependencyError` | `Asgard::Error` | Raised by `validate_deps!` when a cycle is detected in the dependency graph. `run!` catches this and calls `abort` with a clean message. |
+
+```ruby
+begin
+  Asgard.run!(ARGV)
+rescue Asgard::CircularDependencyError => e
+  # This is already handled inside run! — you only need this
+  # if you call validate_deps! directly in your own tooling.
+  abort "circular dependency: #{e.message}"
+end
+```
+
+---
+
+## Dependencies
+
+| Gem | Version | Purpose |
+|---|---|---|
+| [thor](https://github.com/rails/thor) | `~> 1.0` | CLI framework; provides the full task DSL |
+| [dagwood](https://rubygems.org/gems/dagwood) | `~> 1.0` | DAG library for dependency graph resolution and topological sort |
+| [dotenv](https://github.com/bkeepers/dotenv) | `~> 3.0` | `.env` file loading |
+
+---
+
+## Ruby Version Requirement
+
+Asgard requires **Ruby >= 3.2.0**.

data/docs/assets/css/custom.css

@@ -0,0 +1,93 @@
+/* ==========================================================================
+   Asgard documentation — custom styles
+   Material theme handles the heavy lifting; this file adds targeted polish.
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   .loki filename display
+   Used whenever the filename ".loki" or "*.loki" appears inline or in code.
+   -------------------------------------------------------------------------- */
+
+/* Give inline code that looks like a .loki filename a subtle Norse-gold tint */
+code:is([class*="language-"]) .token.string:has-text(".loki"),
+.md-typeset code.loki-file {
+  color: var(--md-accent-fg-color);
+  font-weight: 600;
+}
+
+/* Highlight .loki filenames in directory tree code blocks */
+.md-typeset .highlight .filename {
+  background-color: color-mix(in srgb, var(--md-primary-fg-color) 12%, transparent);
+  border-bottom: 2px solid var(--md-accent-fg-color);
+  border-radius: 4px 4px 0 0;
+  color: var(--md-default-fg-color);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  padding: 0.3rem 0.8rem;
+}
+
+/* --------------------------------------------------------------------------
+   Admonition tweaks — slightly warmer warning border for the "argument"
+   class-level scope warning that appears on the tasks page.
+   -------------------------------------------------------------------------- */
+
+.md-typeset .admonition.warning,
+.md-typeset details.warning {
+  border-left-color: #e6a817;
+}
+
+.md-typeset .admonition.warning > .admonition-title,
+.md-typeset details.warning > summary {
+  background-color: rgba(230, 168, 23, 0.12);
+}
+
+/* --------------------------------------------------------------------------
+   Table of Contents — emphasise the current section a touch more
+   -------------------------------------------------------------------------- */
+
+.md-nav__link--active {
+  font-weight: 600;
+}
+
+/* --------------------------------------------------------------------------
+   Home page feature table (HTML table in index.md)
+   -------------------------------------------------------------------------- */
+
+.md-typeset table:not([class]) td {
+  vertical-align: top;
+}
+
+/* --------------------------------------------------------------------------
+   Execution diagram in dependencies.md — keep it tight and readable
+   -------------------------------------------------------------------------- */
+
+.md-typeset pre code {
+  font-size: 0.85em;
+  line-height: 1.5;
+}
+
+/* --------------------------------------------------------------------------
+   Subtle Norse-shield watermark on the hero block (index page only).
+   Relies on the Material "primary: indigo" palette.
+   -------------------------------------------------------------------------- */
+
+.md-header {
+  box-shadow: 0 2px 8px rgba(63, 81, 181, 0.25);
+}
+
+/* --------------------------------------------------------------------------
+   Code annotations — keep them readable across both light and dark palettes
+   -------------------------------------------------------------------------- */
+
+.md-typeset .md-annotation__index > * {
+  font-size: 0.7rem;
+}
+
+/* --------------------------------------------------------------------------
+   Task-runner specific: distinguish shell prompt lines from output lines
+   in bash code blocks by dimming lines that don't start with '#' or 'asgard'
+   -------------------------------------------------------------------------- */
+
+/* (Future: add targeted styles once MkDocs Material supports per-line
+   highlighting via config; for now this is intentionally minimal.) */

data/docs/changelog.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to Asgard are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asgard adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Removed
+
+- **`var` DSL method** — replaced by native Ruby class variables. Use `@@name ||= "value".freeze` in the class body. Class variables are visible in all task instance methods and in subcommand subclasses, making them the correct tool for shared configuration in a Thor-based task runner. See [Variables](variables.md).
+
+## [0.2.0] — 2026-05-29
+
+### Changed
+
+- `*.loki` files are no longer auto-loaded by default. Pass `--auto-load` to `asgard` to load all `*.loki` files from the project root alphabetically before `.loki`. This is a breaking change for projects using the multi-file layout.
+- Added `--auto-load` as a built-in CLI flag in `Tasks`, visible in `asgard help`
+
+---
+
+## [0.1.2] — 2026-05-29
+
+### Added
+
+- `--version` built-in CLI flag — prints `Asgard::VERSION` and exits; implemented as a `_`-prefixed method in `Tasks` per the gem-owned naming convention
+- `--debug` and `--verbose` built-in `class_option` declarations on `Tasks` — set `$DEBUG`/`$VERBOSE` before any task runs via the `invoke_command` hook in `Asgard::Base`
+- `debug?` and `verbose?` private predicate helpers on `Tasks` — thin wrappers around `$DEBUG` and `$VERBOSE` for use inside task bodies
+- `_` prefix convention for gem-owned methods in `Tasks` — built-in methods use `_` prefix to distinguish them from user-defined tasks
+- `run!` guards against direct invocation of `_`-prefixed commands with a clean error message and exit 1
+- `examples/` directory with working `.loki` files:
+  - `kitchen_sink.loki` — demonstrates the full Thor DSL (all option types, `long_desc`, `class_option`, `default_task`, `map`, `depends_on`, `var`, `no_commands`, `private`)
+  - `server_subcommands.loki` — subcommand group for server management
+  - `db_subcommands.loki` — subcommand group for database management with `depends_on` chaining
+  - `concurrent.loki` — demonstrates parallel task execution with interleaved thread output
+- README sections: Helper methods, Subcommands, Thor wrapper callout
+
+### Fixed
+
+- Replaced `warn`/`exit 1` with `abort` throughout `run!` — `Kernel#warn` is silenced when `$VERBOSE = nil`, which is the default in Ruby 4.0; `abort` writes to `$stderr` regardless
+
+### Changed
+
+- `--debug` and `--verbose` promoted from mapped tasks to `class_option` — they now work as modifiers alongside other commands (e.g. `asgard build --debug`) rather than as standalone commands
+- Removed all references to `just` task runner and `recipe` terminology; Asgard uses "task" throughout
+- `depends_on` parameter renamed from `*recipes` to `*tasks` for consistency
+
+---
+
+## [0.1.1] — 2026-05-28
+
+### Added
+
+- Parallel dependency execution — wrap deps in an array to run them concurrently:
+  `depends_on [:build, :lint]` or `depends_on :setup, [:build, :lint], :deploy`
+- `Asgard.run!(argv)` — single entry point encapsulating find, load, validate, and start
+- `Asgard.load_loki(dir)` — auto-loads all `*.loki` files in a directory alphabetically
+- `Tasks` class pre-defined by the gem (`class Tasks < Asgard::Base`) — task files reopen it without restating the superclass
+- `lib/asgard/tasks.rb` — ships the pre-defined `Tasks` class
+
+### Changed
+
+- Replaced `SimpleFlow` dependency with `Dagwood` — purpose-built DAG library with no extra dependencies and no Ruby 4 compatibility issues
+- `bin/asgard` simplified to two lines: `require "asgard"` + `Asgard.run!(ARGV)`
+- Task file convention: `.loki` is the project root marker and entry point; `*.loki` files each reopen `class Tasks` and are auto-loaded before `.loki`
+- `Asgard.find_task_files` renamed to `Asgard.find_task_file` (singular — only `.loki` is the entry point)
+- `depends_on` now accepts mixed sequential/parallel stages; bare symbols run sequentially, arrays within the splat run in parallel
+- `run!` handles its own errors — missing `.loki` and circular dependencies produce a clean one-line message and exit 1 rather than a backtrace
+- Thread-safe dep deduplication via class-level `_ran_tasks` Set + Mutex replaces Thor's `@_invocations`
+- Removed `import` macro — task files use Ruby class reopening instead of modules
+
+### Removed
+
+- `SimpleFlow` dependency (replaced by `Dagwood`)
+- `logger` gem workaround (was only needed for SimpleFlow on Ruby 4)
+- `*.loki` glob fallback in `find_task_file` — only `.loki` is the auto-discovered entry point
+
+---
+
+## [0.1.0] — 2026-05-28
+
+### Added
+
+- `Asgard::Base` — Thor subclass providing the task DSL
+- `depends_on` — declare task dependencies; dependencies run at most once per invocation
+- `var` — declare static or lazy-evaluated variables available to all tasks
+- `import` — flat-merge a task module into the current class
+- `dotenv` — load a `.env` file into the environment
+- `sh` — run a shell command or multiline heredoc script; exits with the command's status on failure
+- `shebang` — write a script body to a tempfile and execute it with a given interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`, or any custom interpreter)
+- `Asgard.find_task_files` — search current directory and ancestors for task files
+- Task file resolution: `.loki` takes priority; falls back to all `*.loki` files sorted alphabetically
+- `asgard` executable — finds task files, validates dependency graph, dispatches via Thor
+- Circular dependency detection via `SimpleFlow::DependencyGraph` at startup
+- 100% test coverage enforced via SimpleCov (95% minimum threshold)
+- Quality task in `.loki` runs flog after tests
+
+[Unreleased]: https://github.com/MadBomber/asgard/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/MadBomber/asgard/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/MadBomber/asgard/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/MadBomber/asgard/releases/tag/v0.1.0

data/docs/dependencies.md

@@ -0,0 +1,221 @@
+# Task Dependencies
+
+`depends_on` declares what must run before a task. Asgard resolves the dependency graph at startup, validates it for cycles, and executes prerequisites automatically when a task is invoked.
+
+!!! note
+    `desc` and `depends_on` are independent — either can come first. Both must appear before the `def`.
+
+---
+
+## How It Works
+
+When you run `asgard <task>`, Asgard:
+
+1. Validates the full dependency graph for circular references (fails fast with a clear error).
+2. Resolves the dependency stages for the requested task in order.
+3. Executes each stage — running parallel groups in native Ruby threads.
+4. Runs the task itself after all prerequisites complete.
+
+**Deduplication:** each task runs at most once per `asgard` invocation, regardless of how many other tasks declare it as a dependency. This is enforced thread-safely via a class-level `Set` and `Mutex`.
+
+---
+
+## Sequential Dependencies
+
+Bare symbols run one after another in the order declared:
+
+```ruby
+class Tasks
+  desc "Compile the project"
+  def build = sh "rake build"
+
+  depends_on :build
+  desc "Run the test suite"
+  def test = sh "rake test"
+
+  depends_on :test
+  desc "Publish the gem"
+  def release = sh "bundle exec rake release"
+end
+```
+
+```bash
+asgard release   # build → test → release
+```
+
+Multiple sequential dependencies in a single `depends_on` call run left to right:
+
+```ruby
+depends_on :clean, :build, :test
+desc "Clean, build, and test"
+def package = sh "rake package"
+```
+
+---
+
+## Parallel Dependencies
+
+Wrap symbols in an array to declare they can run concurrently. Asgard waits for all tasks in a parallel group to finish before moving to the next stage:
+
+```ruby
+class Tasks
+  desc "Check code style"
+  def lint = sh "bundle exec rubocop"
+
+  desc "Run type checks"
+  def typecheck = sh "bundle exec srb tc"
+
+  depends_on [:lint, :typecheck]
+  desc "Run tests (after lint and typecheck)"
+  def test = sh "bundle exec rake test"
+end
+```
+
+```bash
+asgard test   # lint ∥ typecheck → test
+```
+
+Parallel groups run in native Ruby threads. For CPU-bound work, keep in mind the GVL; for I/O-bound work (shell commands, network), true concurrency is achieved.
+
+---
+
+## Mixed Sequential and Parallel
+
+Mix bare symbols and arrays in a single `depends_on` call. Execution proceeds stage by stage — each stage completes before the next begins:
+
+```ruby
+class Tasks
+  desc "Install dependencies"; def setup  = sh "bundle install"
+  desc "Check code style";     def lint   = sh "bundle exec rubocop"
+  desc "Compile assets";       def build  = sh "rake assets:precompile"
+  desc "Run tests";            def test   = sh "bundle exec rake test"
+  desc "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
+
+  # setup first, then lint+build in parallel, then test, then notify
+  depends_on :setup, [:lint, :build], :test, :notify
+  desc "Full CI pipeline"
+  def ci = puts "CI complete"
+end
+```
+
+```bash
+asgard ci
+```
+
+Execution order:
+
+```
+setup
+  ↓
+lint ∥ build    (concurrent)
+  ↓
+test
+  ↓
+notify
+  ↓
+ci
+```
+
+---
+
+## Deduplication
+
+Each task runs at most once per `asgard` invocation. If multiple tasks declare the same dependency, it executes only on its first encounter:
+
+```ruby
+class Tasks
+  desc "Install gems"
+  def setup = sh "bundle install"
+
+  depends_on :setup
+  desc "Run tests"
+  def test = sh "rake test"
+
+  depends_on :setup
+  desc "Check style"
+  def lint = sh "rubocop"
+
+  depends_on [:test, :lint]
+  desc "Test and lint (setup runs once)"
+  def ci = puts "done"
+end
+```
+
+When `asgard ci` runs, `setup` executes once even though both `test` and `lint` declare it as a dependency. The deduplication set is managed with a `Mutex` so parallel groups are also safe.
+
+---
+
+## 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:
+
+```ruby
+class Tasks
+  depends_on :b
+  desc "Task A"; def a = puts "a"
+
+  depends_on :a
+  desc "Task B"; def b = puts "b"
+end
+```
+
+```bash
+asgard a
+# asgard: circular dependency — TSort::Cyclic: ...
+```
+
+No backtrace is shown — just a single diagnostic line.
+
+---
+
+## depends_on Across Multiple Files
+
+`depends_on` works across `.loki` files because all files reopen the same `class Tasks`. The dependency is recorded when the `def` is encountered, so load order matters:
+
+```ruby
+# build.loki
+class Tasks
+  desc "Compile"
+  def build = sh "rake build"
+end
+
+# test.loki
+class Tasks
+  depends_on :build           # build.loki must be loaded first
+  desc "Test"
+  def test = sh "rake test"
+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`.
+
+---
+
+## depends_on Inside Subcommands
+
+`depends_on` works within subcommand classes exactly as it does at the top level. Dependency scope is per-class:
+
+```ruby
+class DBCommands < Tasks
+  desc "Run migrations"
+  def migrate = sh "rails db:migrate"
+
+  desc "Load seed data"
+  def seed = sh "rails db:seed"
+
+  depends_on :migrate, :seed
+  desc "Migrate then seed"
+  def reset = puts "Done."
+end
+
+class Tasks
+  desc "db SUBCOMMAND", "Manage the database"
+  subcommand "db", DBCommands
+end
+```
+
+```bash
+asgard db reset   # migrate → seed → reset
+```
+
+See [Subcommands](subcommands.md) for the full guide.