asgard 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7920fc28de5f8644ccc7934f576142d433de3fb5af1ac21b28cbd350d930af66
-  data.tar.gz: e651f2956eb2f9fc076548fc04cae92e6835fb508b5960eeda952929d9197253
+  metadata.gz: 839554cd5b16759477245ef561d2769b6d09ea555aa592c8086c2de6bc54450b
+  data.tar.gz: 419b813aaccbd3afbe5bc70be2ada0ba4b99ce3f5fdcc0b5b246b461bc3bd76f
 SHA512:
-  metadata.gz: 19e473102e5850db42c777b9dd824765b9e4a187f1de6f009d80ae85fa1d6992984587a7ca4e9dc40cb301aadc11093826f913d3c5c7dac8e17a47c47f7cdefe
-  data.tar.gz: '09c0f72476c8690f055e6aeb2b052449a4eb9fd415bff06a82e4cd5dc4255cfb8709721a76ae347226b31b8dafcbd3e63a439fcd6f249975f134156f578edb1f'
+  metadata.gz: 8eb7270b4a6668ea0e111f739de651753e927347dd91d5a85275a6b2e014b01ba4c3fc84261174d97f221bf36ac23a4868f3b56ba3df80041a96bf9fa9115397
+  data.tar.gz: 5fb697c0ac1dd087b1d8b521680a7a3ec277b633dfee7dab612dfce6da6ce4a7d1377b916049913f082c2f233567ef3a311cfe60b6dc1945c891ac122b1add43

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed (round 2)
+
+- **Subcommand deps not validated at startup** — `run!` only called `Tasks.validate_deps!`, so circular dependencies and undefined dep names in subcommand groups (classes that inherit from `Asgard::Base` or `Tasks`) were silently ignored. `run!` now snapshots `Asgard::Base.subclasses` before loading task files and validates every newly defined subclass alongside `Tasks`.
+- **Parallel dep thread orphaned on exception** — when a parallel dep group contained one fast-failing task and one slow task, `threads.each(&:join)` re-raised the first thread's exception and abandoned the remaining threads. The slow thread continued running unsupervised after the caller saw the exception. The join loop now collects all thread exceptions before re-raising the first, ensuring every thread completes before execution exits the group.
+- **Dep with required arguments gave a cryptic runtime error** — `depends_on :build` where `build(name)` has required parameters caused `Thor::InvocationError` at task invocation time with no indication of where the problem was. `validate_deps!` now checks the arity of every dep task via `instance_method.parameters` and raises `Asgard::Error` at startup with the task name and required argument count.
+- **Orphaned `depends_on` silently discarded** — a `depends_on` declaration at the end of a class body (or `.loki` file) with no following `desc`/`def` left `@_pending_deps` non-empty but was ignored by `validate_deps!` due to an early `return if _deps.empty?` guard. `validate_deps!` now checks `@_pending_deps` before that guard and raises `Asgard::Error` naming the orphaned dependencies.
+
+### Fixed
+
+- **Parallel dep race condition** — when two parallel tasks shared a common dependency, the second thread could start before the shared dep finished executing. `_ran_tasks` (a single Set) has been replaced with `_running` / `_done` Sets and a per-task `ConditionVariable`. Threads that arrive at an already-running dep now wait for its completion rather than skipping it; the `ensure` block broadcasts completion whether the task succeeds or raises.
+- **`depends_on` silently dropped before `var` or `no_commands`** — Thor uses an integer counter for `@no_commands` that resets to `0` (truthy in Ruby) after any `no_commands` block. The `method_added` guard now checks `@usage` instead: pending deps are only consumed when a command-defining method is added (one preceded by `desc`), so `var` declarations and `no_commands` helpers placed between `depends_on` and `def` no longer silently steal the dependency.
+- **`shebang` ignored its `silent:` keyword argument** — the parameter was accepted but never referenced; the script body is now echoed to stdout unless `silent: true` is passed, matching the behavior of `sh`.
+- **`var` lambdas re-evaluated on every access** — the accessor method now caches its result in a per-instance variable on first call. Lambdas used for computed values (e.g. `` -> { `git describe --tags`.strip } ``) now run exactly once per instance.
+
+### Changed
+
+- **`validate_deps!` detects undefined dependency names** — `depends_on :nonexistent` previously passed validation silently and produced no error at runtime. `validate_deps!` now raises `Asgard::Error` listing every dep name that does not correspond to a defined task. `run!` catches this alongside `CircularDependencyError` and exits with a clean message.
+
+## [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
+- 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
 
@@ -39,8 +89,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `Asgard::Base` — Thor subclass providing the task DSL
-- `depends_on` — declare recipe dependencies; dependencies run at most once per invocation
-- `var` — declare static or lazy-evaluated variables available to all recipes
+- `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
@@ -52,5 +102,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.1.0...HEAD
+[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/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What Asgard Is
+
+Asgard is a Ruby task runner. Users define tasks in `.loki` files by reopening the pre-defined `Tasks` class. The name is intentional: Thor handles the CLI, Asgard is where tasks live, and Loki (the `.loki` file) holds all the tricks.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rake test          # run tests (enforces 95% SimpleCov coverage)
+bundle exec rake quality       # test + flog complexity check
+bundle exec rake build         # build .gem into pkg/
+bundle exec rake install       # install locally
+
+# or use the gem's own .loki file:
+asgard test
+asgard quality
+asgard release
+```
+
+Single test: `ruby -Ilib:test test/test_asgard.rb`
+
+## Architecture
+
+### Entry Point Flow
+
+`bin/asgard` → `Asgard.run!(ARGV)` (`lib/asgard.rb`):
+1. Walk CWD + ancestors for `.loki` (marker only, not a task file)
+2. If `--auto-load` is in argv: glob + sort `*.loki` files and load each alphabetically
+3. Load `.loki` itself last
+4. `Tasks.validate_deps!` — build full dep graph, raise `CircularDependencyError` if cyclic
+5. `Tasks._reset_ran!` — clear execution tracking
+6. `Tasks.start(argv)` — Thor dispatches the command
+
+### Core Classes
+
+| File | Role |
+|------|------|
+| `lib/asgard/base.rb` | DSL engine; inherits Thor, includes Shell |
+| `lib/asgard/shell.rb` | `sh` / `shebang` helpers |
+| `lib/asgard/tasks.rb` | `class Tasks < Asgard::Base` — the convention class users reopen; also holds gem-owned built-in tasks |
+
+### Naming Convention for Gem-Owned Methods
+
+Any task or method defined by Asgard itself inside `Tasks` (i.e. not by the user's `.loki` files) must be prefixed with `_`. This distinguishes built-in gem behavior from user-defined tasks and prevents naming collisions.
+
+```ruby
+# lib/asgard/tasks.rb — gem-owned built-ins use _ prefix
+class Tasks < Asgard::Base
+  desc "--version", "Show version"
+  map "--version" => :_version
+  def _version
+    puts Asgard::VERSION
+    exit
+  end
+end
+```
+
+`method_added` in `Base` already skips `_`-prefixed methods when attaching dependency metadata, so built-ins are naturally excluded from the dependency graph.
+
+Do not define `_`-prefixed methods in user `.loki` files — that namespace is reserved for the gem.
+
+### DSL Mechanics (`lib/asgard/base.rb`)
+
+**`depends_on`** stores stages in `@_pending_deps`. On `method_added`, those stages are popped and stored in `@_deps[method_name]`. Bare symbols are sequential stages; arrays within a `depends_on` call are parallel stages:
+
+```ruby
+depends_on :a, [:b, :c], :d   # stages: [[:a], [:b, :c], [:d]]
+```
+
+**`var`** stores values or lambdas in `@_vars` and creates an instance method that evaluates the lambda once on first access.
+
+**`invoke_command`** (Thor dispatch hook):
+1. Atomically check `@_ran_tasks` Set (with `@_ran_mutex`); return early if already run
+2. Resolve `@_deps` stages → `_build_dep_graph` → `Dagwood::DependencyGraph#parallel_order`
+3. For each parallel group: spawn one thread per task, join; single-task groups run inline
+4. Execute the target task
+
+**`_build_dep_graph(stages)`** converts stages to a DAG hash:
+- `[[:a], [:b, :c], [:d]]` → `{ a: [], b: [:a], c: [:a], d: [:b, :c] }`
+
+### Dependency Resolution
+
+Dagwood topologically sorts the DAG and returns parallel groups. The thread-safe deduplication (`_ran_tasks` Set + Mutex) ensures each task runs exactly once even when multiple tasks share a common dependency.
+
+### Shell Helpers
+
+- `sh(script, silent: false)` — single-line strings use `system(script)`; multi-line strings pipe through `bash -c`; exits with the command's status on failure
+- `shebang(interpreter, script)` — writes script to a tempfile and executes with the named interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, etc.)
+
+## Testing
+
+All tests are in `test/test_asgard.rb` (one file, ~11 named classes). SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
+
+Key test patterns: tests frequently subclass `Asgard::Base` directly (not `Tasks`) to test the engine in isolation, and use `capture_io` for output assertions.
+
+## The `.loki` Format
+
+A `.loki` file is plain Ruby that reopens `Tasks`:
+
+```ruby
+class Tasks
+  var :gem_name, "asgard"
+
+  desc "test", "Run tests"
+  def test = sh "bundle exec rake test"
+
+  depends_on :test
+  desc "release", "Build and release"
+  def release = sh "bundle exec rake release"
+end
+```
+
+By default, only `.loki` is loaded. Pass `--auto-load` to `asgard` to also load all `*.loki` files in the same directory alphabetically before `.loki` is loaded. The bare `.loki` file serves as the project root marker — its content is always loaded last.

data/README.md

@@ -1,8 +1,33 @@
 # Asgard
 
-A [just](https://just.systems)-like task runner for Ruby. Built on [Thor](https://github.com/rails/thor) for argument handling and [Dagwood](https://github.com/rewindio/dagwood) for dependency ordering.
-
-The name comes from Norse mythology: **Thor** is the CLI framework, **Asgard** is the realm where tasks live, and the task file is named **loki** — because Loki holds all the tricks.
+> [!INFO]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory](examples/) contains working `.loki` files demonstrating the full feature set.
+
+<br>
+<table>
+<tr>
+<td width="40%" align="center" valign="top">
+<img src="docs/assets/images/asgard.jpg" alt="Asgard"><br>
+<em>"Loki writes the tricks. Asgard runs them."</em>
+</td>
+<td width="60%" valign="top">
+<strong>Key Features</strong><br>
+
+- <strong>Thor-Powered CLI</strong> — every Thor DSL feature available inside <code>.loki</code> task files<br>
+- <strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code><br>
+- <strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads<br>
+- <strong>Subcommands</strong> — group related tasks under a named namespace<br>
+- <strong>Variables</strong> — static values and lazy-evaluated lambdas via <code>var</code><br>
+- <strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts<br>
+- <strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code><br>
+- <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
+- <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded on demand with <code>--auto-load</code><br>
+- <strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, and <code>--verbose</code> available on every task<br>
+</td>
+</tr>
+</table>
+
+<p>Asgard is a <a href="https://github.com/rails/thor">Thor</a>-based task runner for Ruby projects. Define tasks in <code>.loki</code> files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do — subcommands, typed options, argument validation — is available inside a <code>.loki</code> file.</p>
 
 ## Installation
 
@@ -53,7 +78,7 @@ asgard hello Alice
 
 ### A task with a formal argument declaration
 
-Use `argument` for richer metadata — type checking, enums, and help text:
+Use `argument` for richer metadata — type checking, enums, and help text. **Warning: `argument` is a class-level declaration that applies to every task in the class**, not just the one below it. It is best suited for single-command CLIs or when every task genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
 
 ```ruby
 class Tasks
@@ -114,7 +139,7 @@ end
 
 `depends_on` declares what must run before a task. Each dependency runs at most once per `asgard` invocation regardless of how many tasks declare it. Circular dependencies are caught at startup.
 
-`desc` and `depends_on` are independent — either can come first, both must appear before `def`.
+`desc` and `depends_on` are independent — either can come first, both must appear before `def`. `var` declarations between `depends_on` and `def` are safe and do not consume the pending dependency.
 
 ### Sequential dependencies
 
@@ -213,6 +238,61 @@ end
 
 ---
 
+## Helper methods
+
+Private methods are callable from any task in the same class but are never registered as commands — they won't appear in `--help` output and can't be invoked from the CLI.
+
+```ruby
+class Tasks
+  desc "build", "Compile and package"
+  def build
+    compile("src")
+    package(version)
+  end
+
+  desc "release", "Build and publish"
+  def release
+    build
+    sh "gem push pkg/myapp-#{version}.gem"
+  end
+
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
+
+  def package(ver)
+    sh "tar czf pkg/myapp-#{ver}.tar.gz bin/"
+  end
+end
+```
+
+Helpers can also be shared across multiple `.loki` files by extracting them into a plain Ruby file and loading it explicitly:
+
+```ruby
+# shared/helpers.rb
+module BuildHelpers
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
+end
+
+# .loki
+require_relative "shared/helpers"
+
+class Tasks
+  include BuildHelpers
+
+  desc "build", "Compile the project"
+  def build = compile("src")
+end
+```
+
+---
+
 ## Options shared across all tasks
 
 `class_option` defines an option available to every task in the class:
@@ -271,10 +351,14 @@ end
 
 Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
 
-Pass `silent: true` to suppress the command echo:
+Pass `silent: true` to both `sh` and `shebang` to suppress the script echo:
 
 ```ruby
-def build = sh "rake build", silent: true
+def build   = sh "rake build", silent: true
+def analyze = shebang :python3, <<~PY, silent: true
+  import json
+  print(json.load(open("data.json")))
+PY
 ```
 
 ---
@@ -312,6 +396,64 @@ end
 
 ---
 
+## Subcommands
+
+Group related tasks under a common name using Thor's `subcommand` method. Define a subcommand class that inherits from `Tasks`, then register it with a name and description.
+
+```ruby
+class DeployCommands < Tasks
+  desc "staging", "Deploy to staging"
+  def staging = sh "cap staging deploy"
+
+  desc "production", "Deploy to production"
+  def production = sh "cap production deploy"
+end
+
+class Tasks
+  desc "deploy SUBCOMMAND", "Deploy the application"
+  subcommand "deploy", DeployCommands
+end
+```
+
+```bash
+asgard deploy           # shows deploy subcommand help
+asgard deploy staging
+asgard deploy production
+```
+
+Subcommand tasks have all the same access to helper methods like `sh`, `shebang`, `depends_on`, `var`, and the built-in `--debug`/`--verbose` class options as normal tasks.
+
+`depends_on` only works within a subcommand group exactly as it does at the top level:
+
+```ruby
+class DBCommands < Tasks
+  desc "migrate", "Run pending migrations"
+  def migrate = sh "rails db:migrate"
+
+  desc "seed", "Load seed data"
+  def seed = sh "rails db:seed"
+
+  depends_on :migrate, :seed
+  desc "reset", "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
+```
+
+Each subcommand group can have its own `desc`, `long_desc`, `option`, `class_option`, and `map` declarations, all scoped to that group.
+
+See [`examples/server_subcommands.loki`](examples/server_subcommands.loki) and [`examples/db_subcommands.loki`](examples/db_subcommands.loki) for full working examples.
+
+---
+
 ## `method_option` types reference
 
 | Type | CLI example | Ruby value |
@@ -328,7 +470,7 @@ Common `method_option` keys: `aliases`, `type`, `default`, `required`, `desc`, `
 
 ## Task files
 
-Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. All `*.loki` files in the same directory are auto-loaded alphabetically before `.loki` is loaded.
+Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. `*.loki` files in the same directory are loaded only when `asgard` is invoked with `--auto-load`.
 
 ### Single file
 
@@ -399,9 +541,9 @@ end
 |---|---|
 | `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
 | `Asgard.find_task_file` | Returns path to `.loki` searching from CWD upward, or nil |
-| `Asgard.load_loki(dir)` | Loads all `*.loki` files in dir alphabetically |
+| `Asgard.load_loki(dir)` | Loads all `*.loki` files in dir alphabetically — called by `run!` only when `--auto-load` is passed |
 
-`run!` handles its own errors — a missing `.loki` or a circular dependency both produce a clean one-line message and exit 1.
+`run!` handles its own errors — a missing `.loki`, a circular dependency, or a `depends_on` that names a task that doesn't exist all produce a clean one-line message and exit 1.
 
 ---
 

data/docs/api.md

@@ -0,0 +1,131 @@
+# 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. |
+| `load_loki` | `Asgard.load_loki(dir)` | Loads all `*.loki` files in `dir` alphabetically, excluding `.loki` itself. Called by `run!` only when `--auto-load` is present in `argv`. |
+
+### `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.
+
+---
+
+## `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. |
+| `var` | `var(name, value = nil, &block)` | Declare a named variable. If `value` responds to `call` (lambda/proc) or a block is given, the value is computed lazily on first access. Accessible in task bodies as a method. |
+| `import` | `import(mod)` | Include a module into the current class (thin alias for `include`). |
+| `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?` | private instance method | Returns `$DEBUG`. Available in all task bodies and subcommand classes that inherit from `Tasks`. |
+| `verbose?` | private instance method | Returns `$VERBOSE`. Available in all task bodies and subcommand classes that inherit from `Tasks`. |
+| `--auto-load` | CLI flag (consumed by `run!`) | Triggers loading of all `*.loki` files before the main `.loki` and the requested task. Consumed by `run!` before Thor dispatch. |
+
+---
+
+## `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`. |
+| `_vars` | Hash mapping var name symbols to their static values or callables. |
+| `_ran_tasks` | `Set` of task name symbols that have already run in the current invocation. |
+| `_ran_mutex` | `Mutex` protecting `_ran_tasks` for thread-safe deduplication. |
+| `_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. Checks `_ran_tasks` — skips if this task has already run.
+3. Marks the task as ran.
+4. Resolves dependency stages from `_deps`, builds the Dagwood graph, and executes groups (parallel groups in threads, sequential groups one at a time).
+5. Calls `command.run(self, *args)` to execute the task itself.
+
+---
+
+## 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**.