asgard 0.5.1 → 0.6.0

data/README.md

@@ -3,6 +3,9 @@
 > [!INFO]
 > See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory](examples/) contains working `.loki` files demonstrating the full feature set.
 
+> [!WARNING]
+> Version 0.6.0 has breaking changes to scheduled tasks, watchers and `sh`. Read [Breaking Changes](https://madbomber.github.io/asgard/breaking-changes/) before you upgrade.
+
 <br>
 <table>
 <tr>
@@ -13,27 +16,30 @@
 <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> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
-- <strong>`helper` DSL</strong> — define a method once, available in both class-level DSL calls (<code>header</code>) and inside task instance methods<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 via <code>import</code> from your <code>.loki</code><br>
-- <strong>Scheduled Tasks</strong> — run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code><br>
-- <strong>Watched Files</strong> — run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code><br>
-- <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, <code>--version</code>, and <code>--doctor</code> built-in class options; header/footer DSL for static help text<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>: shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
+- <strong>`helper` DSL</strong>: define a method once, available in both class-level DSL calls (<code>header</code>) and inside task instance methods<br>
+- <strong>Shell Helpers</strong>: <code>sh</code> (alias <code>shebang</code>) runs a command or heredoc under the default shell, or under any registered interpreter when you name one<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 via <code>import</code> from your <code>.loki</code><br>
+- <strong>Scheduled Tasks</strong>: run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code><br>
+- <strong>Watched Files</strong>: run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code><br>
+- <strong>Background Jobs</strong>: <code>sh "mkdocs serve", background: true</code> starts a job that outlives asgard; <code>asgard jobs</code> lists, stops, restarts and cleans them<br>
+- <strong>Built-in Flags</strong>: <code>--debug</code>, <code>--verbose</code>, <code>--version</code>, and <code>--doctor</code> built-in class options; header/footer DSL for static help text<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>
+<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
 
+Asgard requires Ruby 4.0 or later. Scheduled tasks and the file watcher need macOS or Linux, background jobs need a POSIX system (`fork`, `setsid` and `/bin/sh`), and installing compiles one native extension, so a C++17 compiler must be available (Xcode's command-line tools or a distribution's `build-essential` package).
+
 ```bash
 gem install asgard
 ```
@@ -48,7 +54,7 @@ bundle add asgard
 
 ## Tasks
 
-Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` class is pre-defined by the gem — just reopen it and add methods.
+Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` class is pre-defined by the gem; just reopen it and add methods.
 
 ### A task with no parameters
 
@@ -81,7 +87,7 @@ asgard hello Alice
 
 ### A task with a formal argument declaration
 
-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.
+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
@@ -142,7 +148,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, but both must appear before `def`.
 
 ### Sequential dependencies
 
@@ -192,7 +198,7 @@ asgard test   # lint ∥ typecheck → test
 
 ### Mixed sequential and parallel
 
-Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` call. Execution proceeds stage by stage — each stage must complete before the next begins:
+Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` call. Execution proceeds stage by stage; each stage must complete before the next begins:
 
 ```ruby
 class Tasks
@@ -223,7 +229,7 @@ asgard ci executes:
   ci
 ```
 
-`depends_on` also accepts a `Proc`/lambda (or, equivalently, a block) instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately — useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
+`depends_on` also accepts a `Proc`/lambda (or, equivalently, a block) instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately. This is useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
 
 ```ruby
 depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
@@ -232,7 +238,7 @@ def quality = puts "running every *_check task..."
 depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
 def quality2 = puts "same, as a block..."
 
-# do...end for a block spanning multiple statements — braces are for
+# do...end for a block spanning multiple statements; braces are for
 # single-line blocks like the two above. The last expression is still what
 # gets returned and validated.
 depends_on do
@@ -244,7 +250,7 @@ end
 def quality3 = puts "same, minus the slow checks, as a multi-line block..."
 ```
 
-See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-block-form) for the full explanation.
+See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies) for the full explanation.
 
 ---
 
@@ -266,13 +272,13 @@ class Tasks
 end
 ```
 
-Class variables are visible in all task instance methods and in subcommand subclasses — unlike class instance variables (`@name`), which are not accessible inside instance methods.
+Class variables are visible in all task instance methods and in subcommand subclasses, unlike class instance variables (`@name`), which are not accessible inside instance methods.
 
 ---
 
 ## 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.
+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
@@ -297,6 +303,8 @@ class Tasks
   def package(ver)
     sh "tar czf pkg/myapp-#{ver}.tar.gz bin/"
   end
+
+  def version = File.read("VERSION").strip
 end
 ```
 
@@ -328,7 +336,7 @@ def self.version = File.read(...).match(...)[1].freeze
 no_commands { private def version = self.class.version }
 ```
 
-`helper` accepts positional arguments, keyword arguments, and blocks — any signature valid in a Ruby method definition:
+`helper` accepts positional arguments, keyword arguments, and blocks: any signature valid in a Ruby method definition:
 
 ```ruby
 helper(:tag) { |name, ver, prefix: "v"| "#{prefix}#{name}-#{ver}" }
@@ -365,7 +373,7 @@ Add static text above and below the command list in `asgard help` output:
 
 ```ruby
 class Tasks
-  header "my-project — build & release tasks"
+  header "my-project: build & release tasks"
   footer "See https://example.com/docs for details"
 end
 ```
@@ -389,7 +397,10 @@ end
 ```
 
 ```
+asgard v0.6.0 The Mighty Thor and Loki working for you
+
 my-project
+
   deploy targets: staging, production
 
 Commands:
@@ -399,7 +410,12 @@ Options:
   ...
 
 See runbook at wiki/deploy
+
 Maintainer: you@example.com
+
+
+Documentation ... https://madbomber.github.io/asgard
+Github Repo ..... https://github.com/MadBomber/asgard
 ```
 
 Header and footer text is only shown for the general `asgard help` page, not for `asgard help <command>`.
@@ -429,7 +445,7 @@ end
 
 ## Shell helpers
 
-`sh` runs any shell command or multiline heredoc. `shebang` writes a script body to a tempfile and executes it with the given interpreter. Both exit with the command's status code on failure.
+`sh` writes a script body to a tempfile and runs it with a registered interpreter; given a script alone it uses the `default_shell` (bash), for one line or a heredoc. `shebang` is the same method under a longer name, which many authors reserve for scripts in another language. Both return `true` and exit with the command's status code on failure.
 
 ```ruby
 class Tasks
@@ -462,7 +478,18 @@ class Tasks
 end
 ```
 
-Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
+Registered shells: `:bash`, `:sh`, `:python3`, `:python`, `:node`, `:ruby`, `:perl`. Any other symbol runs as itself from `PATH` with a `.tmp` extension, except zsh, fish, csh and tcsh, which get `.sh`, `.fish` and `.csh`. Register your own, with a pinned path or options in front of the script, with `shell`:
+
+```ruby
+class Tasks
+  shell :bash,   "/opt/homebrew/bin/bash"      # what sh and shebang :bash run
+  shell :strict, "bash -eu -o pipefail"
+  shell :uv,     "uv run --script", ext: ".py"
+  default_shell :strict                         # what sh and a nameless shebang run
+end
+```
+
+The name may be left out: `shell "/usr/local/bin/bash -c -w"` registers `:bash`, named after the executable, with the options as its `args`. `default_shell` registers and selects in one line the same way: `default_shell "/usr/local/bin/bash -c -w"`, or `default_shell :strict, "bash", args: "-eu -o pipefail"`. A bare `default_shell :bash` only selects and leaves a pinned entry alone.
 
 Pass `silent: true` to both `sh` and `shebang` to suppress the script echo:
 
@@ -478,7 +505,7 @@ PY
 
 ## Environment variables
 
-`dotenv` loads a `.env` file into the environment before tasks run. Use the `env` Kernel method to read environment variables inside task bodies — it accepts a symbol or string and upcases the key automatically:
+`dotenv` loads a `.env` file into the environment before tasks run. Use the `env` Kernel method to read environment variables inside task bodies. It accepts a symbol or string and upcases the key automatically:
 
 ```ruby
 class Tasks
@@ -501,13 +528,13 @@ end
 |------|-----------|
 | `env(:port, "3000")` | Returns `"3000"` when `PORT` is unset |
 | `env(:api_key)` | Raises `KeyError` when `API_KEY` is missing |
-| `env("DATABASE_URL")` | String name works too — always upcased |
+| `env("DATABASE_URL")` | String name works too; always upcased |
 
 ---
 
 ## Abbreviated command matching
 
-Every task is a Thor command, so you don't have to type the full name — Thor resolves any unambiguous prefix automatically, with no extra code:
+Every task is a Thor command, so you don't have to type the full name: Thor resolves any unambiguous prefix automatically, with no extra code:
 
 ```ruby
 class Tasks
@@ -523,12 +550,12 @@ end
 ```
 
 ```bash
-asgard b        # same as: asgard build   — only task starting with "b"
+asgard b        # same as: asgard build   (only task starting with "b")
 asgard depl     # Ambiguous command depl matches [deploy, deploy_staging]
-asgard deploy   # runs deploy — an exact match always wins, even over a shorter ambiguous prefix
+asgard deploy   # runs deploy; an exact match always wins, even over a shorter ambiguous prefix
 ```
 
-This is Thor's own dispatch behavior, not an Asgard feature — it applies to every task in every `.loki` file automatically. When a prefix matches more than one task, Thor lists the candidates instead of guessing; type enough of the name to disambiguate, or use `map` (below) to pin a short name that stays stable even if a later-added task would otherwise make it ambiguous.
+This is Thor's own dispatch behavior, not an Asgard feature; it applies to every task in every `.loki` file automatically. When a prefix matches more than one task, Thor lists the candidates instead of guessing; type enough of the name to disambiguate, or use `map` (below) to pin a short name that stays stable even if a later-added task would otherwise make it ambiguous.
 
 ---
 
@@ -632,10 +659,11 @@ asgard schedule stop NAME      # stop one entry (persists across reboots and ins
 asgard schedule start NAME     # start a stopped entry, or install just this one
 asgard schedule trigger NAME   # run an installed entry now
 asgard schedule log NAME [-f]  # print (or follow) the entry's log
-asgard schedule remove         # remove all of this project's entries
+asgard schedule remove [NAME]  # remove one entry, or all of this project's
+asgard schedule prune [-n]     # remove every project's entries whose directory is gone (-n: list only)
 ```
 
-`stop`, `start`, `trigger` and `log` also take an entry of another project
+`stop`, `start`, `trigger`, `log` and `remove` also take an entry of another project
 (`list --all` shows them); write `project/name` when two projects share a name.
 
 Jobs run `asgard <task> [options]` from the directory holding `.loki`, with
@@ -667,6 +695,7 @@ Then manage the watcher with the built-in `watcher` command:
 ```bash
 asgard watcher start        # watch this project in the background
 asgard watcher stop         # stop it; a task already running finishes first
+asgard watcher stop --force # stop it and end any running task
 asgard watcher list         # watches, daemon state, each entry's last run (--all: every project's)
 asgard watcher preview      # the command and environment each watch would run
 asgard watcher log [-f]     # print (or follow) the watcher's log
@@ -679,6 +708,44 @@ overlaps itself. Saving a `.loki` file restarts the watcher with the new
 declarations. See [Watched Files](https://madbomber.github.io/asgard/watch/)
 for every keyword, the environment, and file locations.
 
+## Background jobs
+
+A script runs in one of three modes. `sh "rake build"` is the foreground:
+the task waits for it and a failure exits asgard. `sh "mkdocs serve",
+background: true` starts a managed job: the task continues at once, the
+job runs on in its own session with its output in a log, it is still
+running when asgard exits, and `asgard jobs` manages it from then on. A
+trailing `&` in the script is the third mode, detached: the shell exits,
+asgard reports success and keeps no record, and the process is yours to
+find and kill by hand.
+
+```ruby
+class Tasks
+  desc "doc_server", "Serve the documentation"
+  def doc_server = sh "mkdocs serve", background: true   # job doc_server-1
+
+  desc "servers", "Bring up the development stack"
+  def servers
+    sh "docker compose up postgres", background: true    # servers-1
+    sh "bin/rails server",            background: :api   # api
+  end
+end
+```
+
+```bash
+asgard jobs list            # running, exited with a status, or gone (--all: every project's)
+asgard jobs stop servers    # by job name, or by task and the tasks it depends on
+asgard jobs log api -f      # print (or follow) one job's log
+asgard jobs restart api     # stop it, then run its owning task again
+asgard jobs clean           # forget every job that is no longer running
+```
+
+`stop` sends TERM to the job's whole process group and KILL after a
+timeout. A job's pid is verified against its command line before anything
+trusts it, so a pid reused after a reboot shows as `gone`, never as
+running. See [Background Jobs](https://madbomber.github.io/asgard/jobs/)
+for naming, the trampoline, and file locations.
+
 ## `method_option` types reference
 
 | Type | CLI example | Ruby value |
@@ -687,7 +754,7 @@ for every keyword, the environment, and file locations.
 | `:boolean` | `--force` / `--no-force` | `true` / `false` |
 | `:numeric` | `--count 3` | `3` |
 | `:array` | `--tags foo bar baz` | `["foo", "bar", "baz"]` |
-| `:hash` | `--vars KEY:val FOO:bar` | `{"KEY"=>"val", "FOO"=>"bar"}` |
+| `:hash` | `--vars KEY:val FOO:bar` | `{"KEY" => "val", "FOO" => "bar"}` |
 
 Common `method_option` keys: `aliases`, `type`, `default`, `required`, `desc`, `enum`, `banner`.
 
@@ -706,7 +773,7 @@ myproject/
 
 ### Multiple files
 
-Split tasks across files — each reopens `class Tasks`:
+Split tasks across files; each reopens `class Tasks`:
 
 ```
 myproject/
@@ -749,7 +816,7 @@ class Tasks
 end
 ```
 
-In a single-file project, `.loki` can be completely empty — its presence alone marks the project root. In a multi-file project, add at least an `import` call.
+`.loki` is the only file asgard loads on its own, so in a single-file project it holds the tasks. In a multi-file project it needs at least the `import` calls that load the others, and may hold nothing else.
 
 ### Explicit loading
 
@@ -767,14 +834,41 @@ end
 
 ---
 
-## `Asgard` module API
+## Tips
+
+- **Start from working files.** The task files at this repository's root (`.loki`, `quality.loki`, `gem_tasks.loki`, `git.loki`, `doc_tasks.loki`) are a real multi-file project: quality gates that return `:pass` or `:fail`, a background job, a subcommand group, a `helper` feeding the `header`, and a deliberate override for `--doctor`. Copy what fits.
+
+- **More examples.** [MadBomber/dev](https://github.com/MadBomber/dev) holds shared `.loki` libraries used across many repos: gem, git, Rails quality, schedule, status report and iTerm tasks. The [examples directory](examples/) here has one small file per feature.
+
+- **One setup for every project.** Put the tasks, shells and helpers you want everywhere in `~/.loki`, then start each project's `.loki` with `import "~/.loki"`. Outside any project the same file is found by the walk up the tree, so those tasks work in any directory.
+
+- **Give busy tasks a short name with `map`.** `map "t" => "test"` stays stable when a later task would otherwise make the prefix `t` ambiguous. Thor's prefix matching is handy; an alias is dependable.
+
+- **Make bare `asgard` do the common thing.** `default_task :test` (or `:quality`, as this repo does) saves typing on the task you run most.
+
+- **Flags go after the task name.** `asgard build --verbose` runs the task; `asgard --verbose build` prints the help for `build`. Only `--version` and `--doctor` go first.
+
+- **See the tasks by file with `asgard --doctor`.** It lists every `.loki` file that loaded and, under each, the tasks that file defines with their line numbers, plus which `.loki` won the walk up the tree, what every `import` loaded, tasks hidden because they lack a `desc`, and definitions silently replaced by a later one. It works even when the `.loki` will not load.
+
+- **See the commands as a tree with `asgard tree`.** Every command with its description, each subcommand group expanded under its own heading, header and footer included. `help` shows what you can type; `tree` shows how it is organised.
+
+- **Keep helpers out of the command list.** A public method without a `desc` is a hidden task: it runs from the command line and as a dependency. Make helpers `private`, wrap them in `no_commands`, or define them with `helper`.
+
+- **Pass results, not instance variables.** Parallel dependencies each run on their own copy of the task object, so an `@ivar` set in one never reaches the task that depends on it. Return a value and read it with `dep_result(:name)` or `dep_results`; [`examples/bad.loki`](examples/bad.loki) shows the trap.
+
+- **Let gates report, let guards stop.** A quality gate returns `:fail` so every gate runs and the summary shows all failures at once. A guard such as [`examples/confirm.loki`](examples/confirm.loki) raises `Asgard::Error` so nothing after it runs. A dependency's return value never stops its dependent; only an exit, `abort` or `raise` does.
+
+- **Name shell configurations, not shells.** The name you give `shell` is yours: `shell :strict, "bash -eu -o pipefail"` names a bash configuration that stops at the first failing line, and `shell :uv, "uv run --script", ext: ".py"` names a way of running Python. `sh` and `shebang` take a name as an optional first argument (`sh :strict, "..."`); without one they run the `default_shell`, so `default_shell :strict` makes every plain `sh` fail fast.
+
+- **An AI agent is just another shell.** Register a coding agent's CLI with `shell` and a heredoc becomes the prompt: [`examples/robots/.loki`](examples/robots/.loki) wires up `claude -p` in one line, and its `ask` task sends a prompt with a plain `sh :claude, <<~PROMPT`. Any agent that reads a prompt from stdin fits the same way, so a task can review a diff, draft release notes or explain a failing test alongside the tasks that run them.
+
+- **Prefer `background: true` to a trailing `&`.** A managed job gets a name, a log and `asgard jobs stop`; a process detached with `&` leaves no record and must be found with `ps`.
+
+- **Import conditionally.** `.loki` is plain Ruby: `import "quality_rails.loki" if ENV["RAILS_ROOT"]` keeps Rails-only gates out of non-Rails projects, and a block-form `depends_on` picks up whatever `*_check` tasks are loaded.
 
-| Method | Description |
-|---|---|
-| `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
-| `Asgard.find_task_file` | Returns a `Pathname` to `.loki` searching from CWD upward, or `nil` |
+- **Trace loading when something is missing.** `RUBYOPT=-w asgard help` prints each file as `import` loads it; `ASGARD_TRACE=1` turns a one-line load error into the full backtrace with Ruby's "Did you mean?" hint.
 
-`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.
+More tips live in the manual at [Tips](https://madbomber.github.io/asgard/tips/).
 
 ---
 
@@ -784,8 +878,9 @@ end
 git clone git@github.com:MadBomber/asgard.git
 cd asgard
 bundle install
-bundle exec rake test       # run tests (95% coverage minimum enforced)
-bundle exec bin/asgard help # exercise the CLI against this gem's own .loki
+bundle exec bin/asgard test_check  # run tests (95% coverage minimum enforced)
+bundle exec bin/asgard quality     # every quality gate in parallel
+bundle exec bin/asgard help        # exercise the CLI against this gem's own .loki
 ```
 
 ## Contributing

data/bin/asgard

@@ -1,5 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# --version needs nothing but the constant, so answer it before loading
+# Thor and the rest of the gem. Only before the task name: after it,
+# --version is the task's own argument.
+require_relative "../lib/asgard/leading_flag"
+if Asgard.leading_flag?(ARGV, "--version")
+  require_relative "../lib/asgard/version"
+  puts Asgard::VERSION
+  exit
+end
+
 require_relative "../lib/asgard"
 Asgard.run!(ARGV)