asgard 0.3.1 → 0.3.3

data/docs/changelog.md

@@ -10,14 +10,36 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asg
 
 ### Added
 
+- **`--doctor` built-in CLI flag** — diagnoses `.loki` resolution, import chains, and task definitions for the current directory. Handled directly in `Asgard.run!` (same pattern as `--version`), so it works even when a broken file, a circular/undefined dependency, or a silently redefined task would otherwise abort the whole process. Backed by the new `Asgard::Doctor` class. Includes a "Tasks by file" listing — every command grouped by the file it's defined in, as `file:line`, with any silently-overridden task annotated inline (`OVERRIDDEN by ...` / `active — redefines ...`). See [API Reference](api.md#asgarddoctor).
 - **`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).
+- **Flay and Reek quality gates** — `flay_check` checks for structural duplication (mass ≥ 150); `reek` checks code smells. Reviewed findings are grandfathered precisely, per method and detector, via `reek --todo`-generated `exclude:` entries in `.reek.yml` — a genuinely new smell still fails the gate even at an already-reviewed method.
+- **`test_verbose`, `console` tasks** — verbose test output and an IRB console with the gem loaded.
+- **`git.loki`** — per-repo `push`/`pull`/`fetch` tasks.
+- **`typos_check` / `typos_fix` tasks** — spell-checking via the external `typos` CLI (`brew install typos-cli`). Reports `SKIP` (not a failure) if `typos` isn't installed, with a one-line install hint.
+- **`fasterer_check` task** — performance-idiom suggestions from the `fasterer` gem, reported as `WARN` (non-blocking).
+- **`SKIP` / `WARN` quality-gate statuses** — alongside `PASS`/`FAIL`; only `FAIL` blocks `quality`.
+- Every quality gate now writes full detail to a `<gate>_output.txt` file (gitignored) and prints just a one-line summary to stdout.
+- **`asgard tree`** now shows the project header/footer, matching `asgard help`.
+- **`bundler_audit_check` task** — `bundle-audit check --update` against `Gemfile.lock`; `FAIL` on any known vulnerability.
+- **`quality_rails.loki`** — imported only when `Rails` is defined; ships `brakeman_check` as a Rails security-scan example. No wiring needed — `quality` discovers it automatically (see `depends_on` below).
+- **`depends_on` accepts a Proc/lambda**, not just a fixed list — resolved once, in `validate_deps!`, after every `.loki` file has loaded, instead of immediately. Solves "load order matters" for a dependency list that can't be known upfront, e.g. every task ending in `_check` across several files. See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form).
+- **`depends_on` also accepts a block** — `depends_on { ... }` or `depends_on do ... end`, interchangeable with the Proc/lambda form above. Task arguments and a block can't be combined; doing so raises `Asgard::Error`.
+- **The Proc/lambda/block result is now shape-validated** once resolved — it must be an `Array` of `Symbol`/`String` (sequential) or `Array` of `Symbol`/`String` (parallel group) stages, nested no deeper. A bad shape raises a clear `Asgard::Error` naming the task and the offending value instead of a raw `NoMethodError`. See `examples/depends_on_block/{good,bad}/`.
 
 ### 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.
+- **`quality` task** — discovers every `*_check` task at run time (via a `depends_on` Proc) rather than a fixed list, and runs them all in parallel with a colorized PASS/FAIL/WARN/SKIP summary and tally.
+- **`test`, `rubocop`, `reek` renamed to `test_check`, `rubocop_check`, `reek_check`** — consistency with the other gates is what makes `quality`'s automatic discovery possible.
+- **`release` task** — prompts for confirmation unless `-y`/`--yes` is passed.
+- **`Asgard::Base` and `Asgard::Doctor` split into mixins** — `lib/asgard/base/{registry,dependency_graph,task_dsl,dispatch}.rb` and `lib/asgard/doctor/{task_sections,report}.rb`. No behavior change; drops both classes' Reek `TooManyMethods`/`TooManyInstanceVariables` warnings to zero.
+
+### Fixed
+
+- **`bin/asgard`** — switched from `require "asgard"` to `require_relative "../lib/asgard"` so the executable always loads the library shipped alongside it, instead of whatever `asgard` gem happens to be installed separately.
 
 ### Removed
 
+- **`reek_baseline` / `ensure_quality_dir` tasks and `.quality/`** — superseded by precise per-method `exclude:` entries in `.reek.yml` (see the Reek gate entry above).
 - **`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

data/docs/dependencies.md

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

data/docs/getting-started.md

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

data/docs/index.md

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

data/docs/options.md

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

data/docs/shell.md

@@ -2,7 +2,7 @@
 
 Asgard provides two methods for running shell commands and scripts from within task bodies: `sh` for shell commands and heredocs, and `shebang` for polyglot scripts. Both are provided by `Asgard::Shell` and mixed into every `Tasks` instance.
 
-Both methods exit with the command's status code on failure — they do not raise Ruby exceptions.
+Both methods exit with the command's status code on failure — they do not raise Ruby exceptions. `sh` also accepts `exec: true` to replace the asgard process outright instead of forking — see [Handing Off with `exec`](#handing-off-with-exec).
 
 ---
 
@@ -80,6 +80,35 @@ class Tasks
 end
 ```
 
+### Handing Off with `exec`
+
+Pass `exec: true` to hand the command the asgard process itself instead of forking a child. Under the hood this calls `Kernel.exec` rather than `system`, which replaces the running ruby process image with the command — asgard doesn't stick around waiting on it.
+
+Use this for a task's final, long-running command — a dev server, a REPL, anything meant to take over the terminal — so there's no idle ruby process sitting in memory alongside it, and Ctrl-C is handled directly by the command instead of unwinding back through asgard:
+
+```ruby
+class Tasks
+  desc "Documentation server startup"
+  depends_on :doc_builder
+  def doc_server = sh "mkdocs serve", exec: true
+end
+```
+
+Since the process is replaced, nothing after the `sh` call ever runs, and `depends_on` chains upstream of it must already have finished (they have — dependencies run before the task body).
+
+```ruby
+class Tasks
+  desc "Start a REPL — never returns to asgard"
+  def console
+    sh "bundle exec pry", exec: true
+    puts "unreachable"
+  end
+end
+```
+
+!!! note
+    `exec: true` only makes sense for a command meant to run for the lifetime of the process. Don't use it for a step with more work queued after it in the same task.
+
 ---
 
 ## `shebang` — Polyglot Scripts

data/docs/tasks.md

@@ -206,6 +206,46 @@ Without `default_task`, running `asgard` with no arguments displays the help mes
 
 ---
 
+## Abbreviated Command Matching
+
+Every task is a Thor command, and Thor resolves any unambiguous prefix of a command name to that command automatically — no Asgard code involved, and nothing to declare. Given:
+
+```ruby
+class Tasks
+  desc "Check code style with RuboCop"
+  def rubocop_check = sh "bundle exec rubocop"
+
+  desc "Run the test suite"
+  def test_check = sh "bundle exec rake test"
+
+  desc "Run the test suite with verbose output"
+  def test_verbose = sh "bundle exec rake test -v"
+
+  desc "Deploy to production"
+  def deploy = sh "cap production deploy"
+
+  desc "Deploy to staging"
+  def deploy_staging = sh "cap staging deploy"
+end
+```
+
+```bash
+asgard r             # same as: asgard rubocop_check — the only task starting with "r"
+asgard test_c        # same as: asgard test_check     — enough of the name to be unique
+asgard test          # Ambiguous command test matches [test_check, test_verbose]
+asgard deploy        # runs deploy, not deploy_staging — see below
+```
+
+Thor matches on a plain prefix (`command_name.start_with?(typed_string)`), so the shortest string that is still unique for your task set works. Two details worth knowing:
+
+- **An exact full name always wins**, even if it's also a prefix of another task. `asgard deploy` runs `deploy` itself, never the ambiguous-prefix error, because `deploy` is a defined command — not merely a prefix of `deploy_staging`.
+- **An ambiguous prefix produces a clean error listing every candidate** (`Ambiguous command X matches [...]`) rather than guessing or running the alphabetically-first match. Type enough of the name to disambiguate.
+
+!!! tip
+    Because matching depends on every task name currently defined, a short prefix that's unique today can become ambiguous tomorrow when a new task with the same stem is added — e.g. adding `rubocop_fix` alongside `rubocop_check` turns `asgard r` from a clean match into `Ambiguous command r matches [rubocop_check, rubocop_fix]`. Use [`map`](#command-aliases) below for a short name you want to guarantee stays stable regardless of what other tasks get added later.
+
+---
+
 ## Command Aliases
 
 `map` creates short aliases for existing tasks:

data/examples/bad.loki

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

data/examples/depends_on_block/bad/.loki

@@ -0,0 +1,51 @@
+# examples/depends_on_block/bad/.loki
+# BAD example: depends_on block returning a mis-shaped result.
+#
+# Compare with ../good/.loki, which does this correctly:
+#
+#   depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+#     ^                                                                ^
+#     one wrapping [ ] — this is "one stage, containing every matching
+#     task, all running in parallel."
+#
+# It's an easy typo to add a SECOND wrapping array, thinking the outer
+# array is "the list of stages" and the inner one is "this stage's tasks"
+# as two separate concerns:
+#
+#   depends_on { [[all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)]] }
+#                ^                                                        ^
+#                that's one stage too many — the middle array ends up
+#                *inside* a stage as a dependency, not as the stage itself.
+#
+# depends_on's block/Proc result is validated the moment it resolves
+# (during validate_deps!, before any task runs): every stage must be a
+# Symbol/String (sequential) or an Array of Symbol/String (parallel group)
+# — nesting one level deeper than that is rejected with Asgard::Error
+# instead of failing later with a confusing NoMethodError.
+#
+# Run with (from this directory):
+#   asgard quality
+#
+# Expected output (validate_deps! aborts before quality — or any other
+# task — ever runs):
+#   asgard: depends_on proc/block for 'quality' returned invalid dependency
+#   [:a_check, :b_check, :c_check] (Array) in a parallel group; expected a
+#   Symbol or String
+
+class Tasks
+  desc "Run the first check"
+  def a_check = puts "running a_check ..."
+
+  desc "Run the second check"
+  def b_check = puts "running b_check ..."
+
+  desc "Run the third check"
+  def c_check = puts "running c_check ..."
+
+  # BUG: double-wrapped — [[ ... ]] instead of [ ... ]. See comment above.
+  depends_on { [[all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)]] }
+  desc "Run every *_check task in parallel, then report"
+  def quality
+    puts "quality: all *_check tasks passed"
+  end
+end

data/examples/depends_on_block/good/.loki

@@ -0,0 +1,83 @@
+# examples/depends_on_block/good/.loki
+# GOOD example: depends_on with a block instead of a Proc/lambda.
+#
+# A block behaves exactly like `-> { ... }` — it defers resolution to
+# validate_deps! (once, after every .loki file has loaded) instead of
+# resolving the moment depends_on is evaluated. This is the real pattern
+# from this gem's own quality.loki: gather every task whose name ends in
+# `_check`, without having to know their names or load order upfront.
+#
+# The block's return value is validated once it resolves: it must be an
+# Array of stages, each a Symbol/String (sequential) or an Array of
+# Symbol/String (parallel group) — see ../bad/.loki for what happens when
+# that shape is wrong.
+#
+# `{ ... }` braces are used below for the short, single-line blocks (quality,
+# full_cycle) — standard Ruby style reserves `do ... end` for a block that
+# spans multiple statements, shown in smoke further down.
+#
+# Run with (from this directory):
+#   asgard quality
+#
+# Expected output:
+#   running a_check ...
+#   running b_check ...
+#   running c_check ...
+#   quality: all *_check tasks passed
+
+class Tasks
+  desc "Run the first check"
+  def a_check = puts "running a_check ..."
+
+  desc "Run the second check"
+  def b_check = puts "running b_check ..."
+
+  desc "Run the third check"
+  def c_check = puts "running c_check ..."
+
+  # self inside the block is the Tasks class (it's written directly in the
+  # class body), so all_commands can be called bare, with no self.class.
+  # prefix — even though the block itself isn't invoked until later.
+  depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+  desc "Run every *_check task in parallel, then report"
+  def quality
+    puts "quality: all *_check tasks passed"
+  end
+
+  # A block can also return a mix of sequential Symbols and parallel Arrays,
+  # exactly like the plain splat form: depends_on :setup, [:a_check, :b_check], :teardown
+  desc "Prepare fixtures before the checks run"
+  def setup = puts "setup: fixtures ready"
+
+  desc "Clean up fixtures after the checks run"
+  def teardown = puts "teardown: fixtures removed"
+
+  depends_on { [:setup, %i[a_check b_check], :teardown] }
+  desc "setup, then a_check+b_check in parallel, then teardown"
+  def full_cycle
+    puts "full_cycle: done"
+  end
+
+  # A block spanning multiple statements — local variables, some computation
+  # — reads more naturally as do...end than as one long `{ ... }` line.
+  # Whatever it does along the way, the last expression is still what gets
+  # returned and validated: here, [:setup, Array, :teardown], the same shape
+  # as full_cycle above.
+  #
+  # Gotcha: this block runs during validate_deps!, which happens *before*
+  # Thor parses this invocation's CLI options (see the Entry Point Flow in
+  # CLAUDE.md) — so checking `--verbose`/`--debug` in here would always see
+  # the pre-flag default, never what was actually passed on this run. Keep
+  # depends_on blocks limited to shaping the dependency graph itself.
+  depends_on do
+    all_checks  = all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)
+    slow_checks = %i[c_check]
+    fast_checks = all_checks - slow_checks
+
+    [:setup, fast_checks, :teardown]
+  end
+  desc "setup, then every *_check except the slow ones, then teardown"
+  def smoke
+    puts "smoke: done"
+  end
+end

data/examples/kitchen_sink.loki

@@ -181,6 +181,19 @@ class Tasks
     end
   end
 
+  # ── Asgard: sh — run shell commands, single-line and multi-line heredoc ────
+  desc "Show environment info (single-line sh)"
+  def env_info = sh "echo Running #{@@app_name} on $(uname -s)"
+
+  desc "Bootstrap the local environment (multi-line sh / heredoc)"
+  def bootstrap
+    sh <<~SHELL
+      echo "App:  #{@@app_name}"
+      echo "Ruby: $(ruby -v)"
+      echo "Date: $(date)"
+    SHELL
+  end
+
   # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
   no_commands do
     def current_sha

data/gem_tasks.loki

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

data/git.loki

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