asgard 0.2.0 → 0.3.1

data/README.md

@@ -17,12 +17,13 @@
 - <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>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 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>
+- <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
+- <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, and <code>--version</code> built-in class options; header/footer DSL for static help text<br>
 </td>
 </tr>
 </table>
@@ -51,8 +52,8 @@ Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` cl
 
 ```ruby
 class Tasks
-  desc "hello", "Say hello"
-  def hello = sh 'echo "Hello, World!"'
+  desc "Say hello"
+  def hello = puts "Hello, World!"
 end
 ```
 
@@ -67,7 +68,7 @@ Declare positional parameters directly in the method signature. Document them in
 ```ruby
 class Tasks
   desc "hello NAME", "Say hello to NAME"
-  def hello(name = "World") = sh "echo 'Hello, #{name}!'"
+  def hello(name = "World") = puts "Hello, #{name}!"
 end
 ```
 
@@ -88,7 +89,7 @@ class Tasks
            desc:    "Name to greet"
 
   desc "hello NAME", "Say hello to NAME"
-  def hello = sh "echo 'Hello, #{name}!'"
+  def hello = puts "Hello, #{name}!"
 end
 ```
 
@@ -103,7 +104,7 @@ class Tasks
   method_option :count,  aliases: "-n", type: :numeric, default: 1, desc: "Repeat N times"
   def hello(name = "World")
     message = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
-    options[:count].times { sh "echo '#{message}'" }
+    options[:count].times { puts message }
   end
 end
 ```
@@ -128,7 +129,7 @@ class Tasks
   method_option :count, aliases: "-n", type: :numeric, default: 1, desc: "Repeat N times"
   def hello(name = "World")
     message = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
-    options[:count].times { sh "echo '#{message}'" }
+    options[:count].times { puts message }
   end
 end
 ```
@@ -139,7 +140,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`. `var` declarations between `depends_on` and `def` are safe and do not consume the pending dependency.
+`desc` and `depends_on` are independent — either can come first, both must appear before `def`.
 
 ### Sequential dependencies
 
@@ -147,15 +148,15 @@ Bare symbols run one after another in the order declared:
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 
   depends_on :build
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "rake test"
 
   depends_on :test
-  desc "release", "Publish the gem"
+  desc "Publish the gem"
   def release = sh "bundle exec rake release"
 end
 ```
@@ -170,15 +171,15 @@ Wrap symbols in an array to declare they can run concurrently. Asgard waits for
 
 ```ruby
 class Tasks
-  desc "lint", "Check code style"
+  desc "Check code style"
   def lint = sh "bundle exec rubocop"
 
-  desc "typecheck", "Run type checks"
+  desc "Run type checks"
   def typecheck = sh "bundle exec srb tc"
 
   # lint and typecheck run in parallel, test waits for both
   depends_on [:lint, :typecheck]
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "bundle exec rake test"
 end
 ```
@@ -193,16 +194,16 @@ Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` cal
 
 ```ruby
 class Tasks
-  desc "setup",  "Install dependencies"; def setup  = sh "bundle install"
-  desc "lint",   "Check code style";     def lint   = sh "bundle exec rubocop"
-  desc "build",  "Compile assets";       def build  = sh "rake assets:precompile"
-  desc "test",   "Run tests";            def test   = sh "bundle exec rake test"
-  desc "notify", "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
+  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 "ci", "Full CI pipeline"
-  def ci = sh "echo 'CI complete'"
+  desc "Full CI pipeline"
+  def ci = puts "CI complete"
 end
 ```
 
@@ -224,18 +225,24 @@ asgard ci executes:
 
 ## Variables
 
-`var` declares a named value available to all tasks as a method. Pass a lambda for lazy evaluation — it is called once on first use:
+Shared configuration values are declared as Ruby class variables (`@@name`) at the top of the class body. Use `||=` so the first declaration wins when multiple `.loki` files reopen `Tasks`, and `.freeze` to prevent mutation:
 
 ```ruby
 class Tasks
-  var :app,     "myapp"
-  var :version, -> { `git describe --tags`.strip }
+  @@app     ||= "myapp".freeze
+  @@max_jobs ||= 4
 
-  desc "tag", "Create a release tag"
-  def tag = sh "git tag #{app}-#{version}"
+  desc "Create a release tag"
+  def tag = sh "git tag #{@@app}-#{version}"
+
+  private
+
+  def version = `git describe --tags`.strip
 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.
+
 ---
 
 ## Helper methods
@@ -244,13 +251,13 @@ Private methods are callable from any task in the same class but are never regis
 
 ```ruby
 class Tasks
-  desc "build", "Compile and package"
+  desc "Compile and package"
   def build
     compile("src")
     package(version)
   end
 
-  desc "release", "Build and publish"
+  desc "Build and publish"
   def release
     build
     sh "gem push pkg/myapp-#{version}.gem"
@@ -268,6 +275,40 @@ class Tasks
 end
 ```
 
+### The `helper` DSL method
+
+Some values need to be available in both class context (e.g. inside `header`) and inside task instance methods. `helper` defines the method once in both contexts:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  helper(:version) {
+    File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  }
+
+  header "#{@@project} v#{version}"   # class context
+
+  desc "Show the current version"
+  def show_version
+    puts version                        # instance context
+  end
+end
+```
+
+Without `helper`, achieving this requires two separate definitions:
+
+```ruby
+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:
+
+```ruby
+helper(:tag) { |name, ver, prefix: "v"| "#{prefix}#{name}-#{ver}" }
+```
+
 Helpers can also be shared across multiple `.loki` files by extracting them into a plain Ruby file and loading it explicitly:
 
 ```ruby
@@ -286,13 +327,60 @@ require_relative "shared/helpers"
 class Tasks
   include BuildHelpers
 
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = compile("src")
 end
 ```
 
 ---
 
+## Help header and footer
+
+Add static text above and below the command list in `asgard help` output:
+
+```ruby
+class Tasks
+  header "my-project — build & release tasks"
+  footer "See https://example.com/docs for details"
+end
+```
+
+Multiple calls accumulate. `header` appends each line (top to bottom); `footer` prepends each line (bottom to top), so content from a later-loaded `.loki` file sits closer to the commands:
+
+```ruby
+# .loki
+class Tasks
+  header "my-project"
+  footer "Maintainer: you@example.com"
+end
+
+import "*.loki"
+
+# deploy.loki
+class Tasks
+  header "  deploy targets: staging, production"
+  footer "See runbook at wiki/deploy"
+end
+```
+
+```
+my-project
+  deploy targets: staging, production
+
+Commands:
+  ...
+
+Options:
+  ...
+
+See runbook at wiki/deploy
+Maintainer: you@example.com
+```
+
+Header and footer text is only shown for the general `asgard help` page, not for `asgard help <command>`.
+
+---
+
 ## Options shared across all tasks
 
 `class_option` defines an option available to every task in the class:
@@ -320,7 +408,7 @@ end
 
 ```ruby
 class Tasks
-  desc "setup", "Bootstrap the development environment"
+  desc "Bootstrap the development environment"
   def setup
     sh <<~SHELL
       brew install redis postgresql
@@ -330,7 +418,7 @@ class Tasks
     SHELL
   end
 
-  desc "analyze", "Run Python data analysis"
+  desc "Run Python data analysis"
   def analyze
     shebang :python3, <<~PYTHON
       import json
@@ -339,7 +427,7 @@ class Tasks
     PYTHON
   end
 
-  desc "bundle_assets", "Build frontend assets with esbuild"
+  desc "Build frontend assets with esbuild"
   def bundle_assets
     shebang :node, <<~JS
       const esbuild = require("esbuild")
@@ -365,18 +453,31 @@ PY
 
 ## Environment variables
 
-`dotenv` loads a `.env` file into the environment before tasks run:
+`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
   dotenv              # loads .env
   dotenv ".env.local" # or a specific file
 
-  desc "check", "Print the app name from .env"
-  def check = sh "echo $APP_NAME"
+  desc "Start the server"
+  def start
+    sh "puma -p #{env(:port, '3000')} -e #{env(:rack_env, 'development')}"
+  end
+
+  desc "Deploy the app"
+  def deploy
+    sh "cap #{env(:deploy_target)} deploy"  # raises KeyError if DEPLOY_TARGET is unset
+  end
 end
 ```
 
+| Call | Behaviour |
+|------|-----------|
+| `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 |
+
 ---
 
 ## Command aliases
@@ -389,7 +490,7 @@ class Tasks
   map "--v" => "version"
   map "t"   => "test"
 
-  desc "version", "Print the version"
+  desc "Print the version"
   def version = puts Asgard::VERSION
 end
 ```
@@ -402,10 +503,10 @@ Group related tasks under a common name using Thor's `subcommand` method. Define
 
 ```ruby
 class DeployCommands < Tasks
-  desc "staging", "Deploy to staging"
+  desc "Deploy to staging"
   def staging = sh "cap staging deploy"
 
-  desc "production", "Deploy to production"
+  desc "Deploy to production"
   def production = sh "cap production deploy"
 end
 
@@ -421,20 +522,20 @@ 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.
+Subcommand tasks have all the same access to `sh`, `shebang`, `depends_on`, and the built-in `--debug`/`--verbose` class options as normal tasks. `@@` class variables declared on `Tasks` are also visible in subcommand subclasses.
 
 `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"
+  desc "Run pending migrations"
   def migrate = sh "rails db:migrate"
 
-  desc "seed", "Load seed data"
+  desc "Load seed data"
   def seed = sh "rails db:seed"
 
   depends_on :migrate, :seed
-  desc "reset", "Migrate then seed"
+  desc "Migrate then seed"
   def reset = puts "Done."
 end
 
@@ -470,7 +571,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. `*.loki` files in the same directory are loaded only when `asgard` is invoked with `--auto-load`.
+Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. Additional `*.loki` files are loaded only when your `.loki` file explicitly calls `import`.
 
 ### Single file
 
@@ -485,16 +586,23 @@ Split tasks across files — each reopens `class Tasks`:
 
 ```
 myproject/
-  .loki          ← entry point, can be empty
+  .loki          ← entry point; calls import to load task files
   build.loki
   deploy.loki
   test.loki
 ```
 
+The `.loki` entry file must call `import` to load the other task files. It also marks the project root for auto-discovery:
+
+```ruby
+# .loki
+import "*.loki"
+```
+
 ```ruby
 # build.loki
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 end
 ```
@@ -503,7 +611,7 @@ end
 # test.loki
 class Tasks
   depends_on :build
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "bundle exec rake test"
 end
 ```
@@ -512,21 +620,21 @@ end
 # deploy.loki
 class Tasks
   depends_on :test
-  desc "deploy", "Deploy to production"
+  desc "Deploy to production"
   def deploy = sh "cap production deploy"
 end
 ```
 
-The `.loki` entry point can be completely empty — it only needs to exist to mark the project root.
+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.
 
 ### Explicit loading
 
-Load any Ruby or `.loki` file manually from `.loki`:
+Load any Ruby or `.loki` file manually from `.loki`. Use `require_relative` for plain Ruby; use `import` for `.loki` files (it enforces the extension and is idempotent):
 
 ```ruby
 # .loki
 require_relative "shared/helpers"
-require_relative "ci.loki"
+import "ci.loki"
 
 class Tasks
   # additional tasks
@@ -540,8 +648,7 @@ end
 | Method | Description |
 |---|---|
 | `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 — called by `run!` only when `--auto-load` is passed |
+| `Asgard.find_task_file` | Returns a `Pathname` to `.loki` searching from CWD upward, or `nil` |
 
 `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

@@ -11,8 +11,7 @@ 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`. |
+| `find_task_file` | `Asgard.find_task_file → Pathname, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns a `Pathname` of the first match, or `nil` if none is found. |
 
 ### `run!` Details
 
@@ -30,6 +29,82 @@ After loading task files, it calls `Tasks.validate_deps!` (circular dependency c
 
 ---
 
+## 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") → Pathname, nil` | `Pathname` or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns a `Pathname` for the first match, 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 a `Pathname` or `nil`. Does not load the file. `Pathname` is accepted by `import`, `dotenv`, `load`, and standard Ruby file methods — no `.to_s` conversion needed in common usage.
+
+```ruby
+if (path = loki_up("gem_tasks.loki"))
+  import path          # Pathname accepted directly
+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).
@@ -37,9 +112,10 @@ After loading task files, it calls `Tasks.validate_deps!` (circular dependency c
 | 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. |
+| `header` | `header(text)` | Append a line of text shown above the commands list in `asgard help`. Each call adds another line. No-op for per-command help. |
+| `footer` | `footer(text)` | Prepend a line of text shown below the options block in `asgard help`. Each call inserts above the previous lines. No-op for per-command help. |
+| `no_negate` | `no_negate(*names)` | Suppress `[--no-name]` / `[--skip-name]` help entries for one or more boolean class options. Call after the `class_option` declaration. |
 | `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. |
@@ -64,10 +140,9 @@ depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently
 |---|---|---|
 | `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. |
+| `class_option :version` | class option | `--version` flag. Handled by `Asgard.run!` before the `.loki` file is loaded — prints `Asgard::VERSION` and exits. `no_negate :version` suppresses the `[--no-version]` / `[--skip-version]` help entries. |
+| `debug?` | Kernel module function | Returns `$DEBUG`. Available everywhere via `Kernel`. |
+| `verbose?` | Kernel module function | Returns `$VERBOSE`. Available everywhere via `Kernel`. |
 
 ---
 
@@ -78,9 +153,10 @@ These are implementation details exposed for extensibility. Prefer the DSL metho
 | 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. |
+| `_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. |
 
 ---
@@ -90,10 +166,10 @@ These are implementation details exposed for extensibility. Prefer the DSL metho
 `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.
+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.
 
 ---
 

data/docs/changelog.md

@@ -8,6 +8,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asg
 
 ## [Unreleased]
 
+### Added
+
+- **`helper` DSL method** — defines a method available in both class context (e.g. inside `header`) and instance context (inside task methods) with a single declaration. Eliminates the manual `def self.name` + `no_commands { private def name = self.class.name }` boilerplate. Supports positional arguments, keyword arguments, and block arguments. See [Helper Methods](helpers.md).
+
+### Changed
+
+- **`quality` task** — all three gates (`test`, `rubocop`, `flog_check`) now run in parallel. Each gate captures its own pass/fail result; output is suppressed on pass and filtered to failures only on fail. A summary table is printed after all gates complete.
+
+### 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